更新 wiki

.qoder/repowiki/knowledge/zh/pnpm 多包工作区与镜像源管理/pnpm 多包工作区与镜像源管理.md

@@ -9,33 +9,34 @@ source_files:
     - frontend/package.json
     - frontend_v2/package.json
     - frontend_v2/pnpm-workspace.yaml
+    - frontend/pnpm-workspace.yaml
     - frontend_v2/.npmrc
 ---
 
-## 1. 使用的系统/工具链
-- **包管理器**：统一使用 pnpm（v11），通过 `packageManager` 字段锁定版本，确保团队一致。
-- **锁文件策略**：后端 `backend/` 提交 `pnpm-lock.yaml`；前端 `frontend/` 同时存在 `pnpm-lock.yaml` 与 `package-lock.json`（后者为历史遗留）；`frontend_v2/` 仅提交 `pnpm-lock.yaml`。
-- **私有仓库/镜像**：`frontend_v2/.npmrc` 配置淘宝镜像 `https://registry.npmmirror.com/`；`frontend/` 未显式配置 `.npmrc`，默认走官方源。
-- **无 vendor 目录**：三个子项目均未将 `node_modules` 或第三方源码纳入版本控制，依赖通过安装生成。
+本仓库采用 pnpm 作为统一的依赖管理工具，通过 packageManager 字段锁定版本，并在后端（backend）与两个前端工程（frontend、frontend_v2）中分别维护各自的依赖声明。核心特征如下：
 
-## 2. 关键文件与包
-- `backend/package.json` — 后端 API 依赖声明（Express、Sequelize、MySQL2、JWT、Axios、Zod、AWS S3 SDK、Winston、ioredis 等）。
-- `frontend/package.json` — 旧版前端（Vue 3 + Element Plus + Vite）依赖。
-- `frontend_v2/package.json` — 新版前端模板（Soybean Admin，基于 Vue 3 + Naive UI + UnoCSS + TypeScript）。
-- `frontend_v2/pnpm-workspace.yaml` — 定义 Monorepo 工作区，包含 `packages/*` 下的内部包（@sa/axios、@sa/color、@sa/hooks、@sa/materials、@sa/utils、@sa/scripts、@sa/uno-preset）。
-- `frontend_v2/.npmrc` — 指定 npm 镜像源。
-- 各子项目 `.gitignore` 均忽略 `node_modules/`、`dist/`、`.env*` 等。
+1. 包管理器与版本锁定
+   - backend/package.json 与 frontend/package.json 均声明 packageManager: pnpm@11.5.2，确保团队使用一致的 pnpm 版本。
+   - 各子项目根目录均生成并随代码提交 lockfile（pnpm-lock.yaml），保证安装可复现；frontend 同时存在 package-lock.json，但实际构建脚本由 pnpm 驱动。
+   - frontend_v2 额外在 engines 中约束 Node >= 20.19.0、pnpm >= 10.5.0。
 
-## 3. 架构与约定
-- **Monorepo 结构**：`frontend_v2/` 采用 pnpm workspace，根 `package.json` 作为聚合入口，业务代码在 `src/`，可复用能力下沉到 `packages/` 下以 `workspace:*` 协议引用。
-- **版本范围策略**：`backend/` 和 `frontend/` 的依赖普遍使用 `^major.minor` 宽泛范围，便于自动升级；`frontend_v2/` 则对核心依赖使用精确版本号（如 `vue: 3.5.34`、`naive-ui: 2.44.1`），配合 `simple-git-hooks` 的 `update-pkg` 脚本统一管理更新。
-- **Node 引擎约束**：`frontend_v2/` 通过 `engines` 强制 Node ≥ 20.19.0、pnpm ≥ 10.5.0，避免环境差异导致的依赖解析问题。
-- **构建期依赖隔离**：`frontend_v2/pnpm-workspace.yaml` 中 `allowBuilds` 明确禁止 esbuild、@parcel/watcher 等构建工具在工作区内被提升，减少重复安装。
+2. 私有/共享包与工作区（Workspace）
+   - frontend_v2 是真正的 pnpm workspace 工程，pnpm-workspace.yaml 将 packages/* 纳入工作区，并通过 linkWorkspacePackages: true 启用本地包互链。
+   - 业务应用通过 workspace:* 协议引用内部包（如 @sa/axios、@sa/hooks、@sa/materials 等），实现跨包复用与统一升级。
+   - frontend 也包含 pnpm-workspace.yaml，但仅配置了 allowBuilds.esbuild: true，未定义 packages，说明其本身不是工作区根。
 
-## 4. 开发者应遵循的规则
-1. **统一使用 pnpm**：新增依赖一律通过 `pnpm add [-D] <pkg>` 操作，不要手动编辑 `package.json` 后自行安装。
-2. **不提交 node_modules**：所有子项目的 `.gitignore` 已忽略 `node_modules/`，请勿将其纳入版本控制。
-3. **镜像源一致性**：新成员应在本地 `.npmrc` 中配置 `registry=https://registry.npmmirror.com/`，与 `frontend_v2/` 保持一致，避免下载缓慢或失败。
-4. **Monorepo 内共享包**：如需在 `frontend_v2/packages/` 间共享代码，使用 `workspace:*` 协议并在 `pnpm-workspace.yaml` 的 `packages` 列表中添加路径。
-5. **依赖版本策略**：公共库建议固定主版本（`^x.y.z`），框架核心依赖参考 `frontend_v2/` 的精确版本写法以保持稳定性。
-6. **更新流程**：优先使用 `pnpm update` 或 `pnpm sa update-pkg`（在 `frontend_v2/` 中）进行批量升级，并检查 `pnpm-lock.yaml` 变更后再提交。
+3. 镜像源与网络加速
+   - frontend_v2/.npmrc 全局设置 registry=https://registry.npmmirror.com/，所有 npm 包从国内镜像拉取。
+   - 未发现 .npmrc 中的私有 registry 或 auth token 配置，表明当前未接入企业私有 npm 源。
+
+4. 依赖分类与更新策略
+   - 所有第三方库按运行时依赖（dependencies）与开发依赖（devDependencies）清晰拆分，无 peerDependencies 混用。
+   - frontend_v2 提供 update-pkg 脚本（基于 sa update-pkg）辅助批量升级依赖；commit hook 中集成 lint/typecheck/fmt，间接保障依赖变更质量。
+
+5. 容器化与安装隔离
+   - 各子项目均有独立 Dockerfile，依赖安装发生在容器内，结合 lockfile 保证构建一致性；node_modules 未被 git 跟踪，符合最佳实践。
+
+开发者约定：
+- 新增依赖必须写入对应子项目的 package.json，并重新运行 pnpm install 以更新 lockfile。
+- 若需引入新的内部共享包，应在 frontend_v2/packages 下创建并按 workspace:* 引用。
+- 修改 .npmrc 或 registry 前需评估对 CI/CD 的影响。