ui 优化

.qoder/repowiki/knowledge/zh/pnpm 包管理与锁定文件策略/pnpm 包管理与锁定文件策略.md

@@ -0,0 +1,44 @@
+---
+kind: dependency_management
+name: pnpm 包管理与锁定文件策略
+category: dependency_management
+scope:
+    - '**'
+source_files:
+    - backend/package.json
+    - frontend/package.json
+    - backend/pnpm-lock.yaml
+    - frontend/pnpm-lock.yaml
+    - frontend/pnpm-workspace.yaml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+---
+
+本仓库采用 pnpm 作为统一的 Node.js 依赖管理工具，前后端各自维护独立的 package.json，并通过各自的 pnpm-lock.yaml 锁定依赖版本，确保构建可复现。
+
+### 1. 使用的系统与工具
+- 包管理器：pnpm（通过 packageManager 字段强制使用 pnpm@11.5.2）
+- 锁文件：backend/pnpm-lock.yaml、frontend/pnpm-lock.yaml
+- 前端工作区配置：frontend/pnpm-workspace.yaml（仅启用 esbuild 构建支持）
+- Docker 构建：后端与前端 Dockerfile 均 COPY package.json + pnpm-lock.yaml，在镜像内执行安装
+
+### 2. 关键文件与位置
+- backend/package.json — Express/Sequelize 等后端依赖声明
+- frontend/package.json — Vue3/Element Plus/Vite 等前端依赖声明
+- backend/pnpm-lock.yaml / frontend/pnpm-lock.yaml — 精确依赖快照
+- frontend/pnpm-workspace.yaml — pnpm workspace 基础配置
+- DEPLOY.md、scripts/upload.sh — 部署脚本中显式包含 lock 文件上传
+
+### 3. 架构与约定
+- 双包根结构：backend 与 frontend 各自为独立 npm 项目，无跨包共享依赖；每个目录有自己 node_modules、pnpm-lock.yaml
+- 版本范围：所有依赖使用 ^ 语义化版本前缀，由 pnpm 解析到具体版本并写入 lock 文件
+- 锁定文件纳入版本控制：lock 文件随代码提交，保证 CI/生产环境安装结果一致
+- 忽略 node_modules：前后端 .gitignore 均排除 node_modules/，避免将本地缓存入库
+- 私有源/代理：未发现 .npmrc、.pnpmrc 或 NPM_CONFIG_* 环境变量，默认使用官方 npm registry
+
+### 4. 开发者应遵循的规则
+- 始终使用 pnpm 安装依赖：pnpm install（禁止改用 npm/yarn）
+- 新增/升级依赖后必须提交对应的 pnpm-lock.yaml 变更
+- 不要手动编辑 lock 文件，使用 pnpm add/update/remove 命令操作
+- 在容器/Docker 环境中依赖安装阶段不应跳过 lock 文件校验
+- 如需切换 npm 源或添加私有 registry，应在仓库根或对应子项目下提供 .npmrc/.pnpmrc 并纳入版本控制