---
kind: dependency_management
name: pnpm 单仓依赖管理（前后端双 package.json）
category: dependency_management
scope:
    - '**'
source_files:
    - backend/package.json
    - frontend/package.json
    - backend/pnpm-lock.yaml
    - frontend/pnpm-lock.yaml
    - frontend/pnpm-workspace.yaml
    - .pnpm-store/v11/index.db
---

## 系统概览
本仓库采用 pnpm 作为统一的包管理器，前后端各自维护独立的 `package.json`，通过根级 `.pnpm-store/v11/` 共享全局缓存，实现跨子项目的依赖去重与快速安装。未使用 pnpm workspace 的 monorepo 模式，而是以“多 package.json + 共享 store”的方式组织。

## 关键文件与位置
- 后端依赖声明：`backend/package.json`（Express、Sequelize、MySQL2、JWT、Axios、Zod、AWS S3 SDK、Winston、ioredis 等）
- 前端依赖声明：`frontend/package.json`（Vue3、Element Plus、Vite、Axios、vue-router 等）
- 锁文件：`backend/pnpm-lock.yaml`（lockfileVersion 9.0，记录精确版本与 integrity）；`frontend/pnpm-lock.yaml`（存在但未在工具输出中展开）
- 前端工作区配置：`frontend/pnpm-workspace.yaml`（仅启用 esbuild 构建）
- 全局缓存目录：`.pnpm-store/v11/`（按哈希分片存储已安装包）
- 部署文档约束：`DEPLOY.md` 明确固定 Node 镜像为 `node:22-alpine`，并强调 `packageManager` 字段锁定 pnpm 版本

## 架构与约定
- 包管理器锁定：两个 `package.json` 均声明 `packageManager: "pnpm@11.5.2"`（前端附带 sha512 校验），确保 CI/本地安装使用相同 pnpm 版本。
- 版本策略：依赖统一使用 `^` 语义化范围（如 `express ^4.21`、`axios ^1.7`、`element-plus ^2.3.14`），由 pnpm-lock.yaml 固化实际解析到的具体版本与完整性校验值。
- 依赖隔离：前后端 node_modules 独立安装，不共享同一份 `node_modules`，避免运行时冲突；但通过 `.pnpm-store` 共享磁盘缓存，减少重复下载。
- 无私有源/代理配置：未发现 `.npmrc`、`.pnpmrc` 或 registry 相关设置，默认使用 npm 官方源。
- 无 vendoring：未将第三方包直接提交到仓库，依赖完全通过 pnpm 从远端拉取。

## 开发者应遵循的规则
1. **新增/升级依赖**：仅在对应子项目（`backend/` 或 `frontend/`）的 `package.json` 中修改，然后运行 `pnpm install` 生成/更新该子项目的 `pnpm-lock.yaml`。
2. **不要手动编辑 lock 文件**：所有版本变更通过 pnpm 命令触发，保证 integrity 与依赖树一致性。
3. **保持 packageManager 字段同步**：若升级 pnpm 主版本，需同时更新前后端 `package.json` 中的 `packageManager` 值。
4. **CI/容器环境**：基于 `node:22-alpine` 镜像，pnpm 版本由 `packageManager` 字段自动锁定，无需额外指定。
5. **不使用 workspace 聚合脚本**：当前未定义根级 scripts 来并行安装前后端，建议在各自目录内执行 `pnpm install`。