From bb9c8bde5b10ff849f3d09b7fbac9ebabd53d2b8 Mon Sep 17 00:00:00 2001
From: Lyda <1829913225@qq.com>
Date: Mon, 18 May 2026 20:01:40 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20package.json=20?=
 =?UTF-8?q?=E5=8F=8A=20lock=20=E6=96=87=E4=BB=B6=E7=9A=84=E4=BE=9D?=
 =?UTF-8?q?=E8=B5=96=E7=AE=A1=E7=90=86=E8=A7=84=E8=8C=83,=E5=8C=85?=
 =?UTF-8?q?=E5=90=AB=E4=BE=9D=E8=B5=96=E5=8F=98=E6=9B=B4=E8=AF=84=E5=AE=A1?=
 =?UTF-8?q?=E3=80=81=E7=A6=81=E6=AD=A2=E6=89=8B=E5=8A=A8=E4=BF=AE=E6=94=B9?=
 =?UTF-8?q?=20lock=20=E6=96=87=E4=BB=B6=E5=92=8C=E7=89=88=E6=9C=AC?=
 =?UTF-8?q?=E5=8F=B7=E4=BD=BF=E7=94=A8=E8=A7=84=E8=8C=83=E4=B8=89=E9=A1=B9?=
 =?UTF-8?q?=E8=A7=84=E5=88=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 references/json.package.md | 96 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 references/json.package.md

diff --git a/references/json.package.md b/references/json.package.md
new file mode 100644
index 0000000..224fbd4
--- /dev/null
+++ b/references/json.package.md
@@ -0,0 +1,96 @@
+# 基础代码规范 `[Json.Package]`
+
+> - includes `package.json` `package-lock.json` `yarn.lock` `pnpm-lock.yaml`
+
+下面是 package.json 及 lock 文件的依赖管理规范
+
+## 依赖变更需经评审 `[Json.Package.DependencyChangeReview]`
+
+> - severity `error`
+
+- 禁止随意添加、删除、修改依赖
+- 新增依赖需在 PR 描述中说明引入理由、使用场景及替代方案评估
+- 升级依赖大版本需经团队评审，评估 Breaking Changes 影响
+- 删除依赖前确认无其他模块引用
+
+### Example: 依赖变更
+
+#### Good: 有明确理由并评审通过
+
+```json
+// PR 描述中说明：
+// 引入 lodash-es 用于高性能数组操作，
+// 替代方案评估：手写工具函数可维护性差，同意引入
+{
+  "dependencies": {
+    "lodash-es": "^4.17.21"
+  }
+}
+```
+
+#### Bad: 随意添加未评审依赖
+
+```json
+// 无说明直接提交
+{
+  "dependencies": {
+    "some-random-lib": "^1.0.0"
+  }
+}
+```
+
+## lock 文件禁止手动修改 `[Json.Package.NoManualLockEdit]`
+
+> - severity `error`
+
+- 禁止直接手动编辑 lock 文件（package-lock.json / yarn.lock / pnpm-lock.yaml）
+- lock 文件只能通过包管理器命令（npm/yarn/pnpm install/add/remove/update）自动生成
+- PR 中 lock 文件变更需与 package.json 变更对应，禁止出现不一致情况
+
+### Example: lock 文件变更
+
+#### Good: 通过命令自动生成
+
+```bash
+# 正确方式：使用包管理器命令
+pnpm add lodash-es
+# 或
+pnpm remove unused-lib
+```
+
+#### Bad: 手动编辑 lock 文件
+
+```yaml
+# 手动修改 pnpm-lock.yaml 中的 checksum 或版本号
+```
+
+## 依赖版本号使用 caret(^) 或波浪号(~) `[Json.Package.DependencyVersion]`
+
+- 生产依赖（dependencies）使用 `^` 允许小版本和补丁版本更新
+- 开发依赖（devDependencies）可使用 `~` 锁定小版本
+- 禁止锁定精确版本（无符号或 `=`），除非存在特殊兼容性要求
+
+### Example: 版本号规范
+
+#### Good: 使用 ^ 或 ~
+
+```json
+{
+  "dependencies": {
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "eslint": "~8.50.0"
+  }
+}
+```
+
+#### Bad: 锁定精确版本无说明
+
+```json
+{
+  "dependencies": {
+    "vue": "3.3.4"
+  }
+}
+```