---
kind: dependency_management
name: 基于 pnpm 与 Docker 的前后端依赖管理
category: dependency_management
scope:
    - '**'
source_files:
    - backend/package.json
    - frontend/package.json
    - backend/pnpm-lock.yaml
    - frontend/pnpm-lock.yaml
    - backend/Dockerfile
    - frontend/Dockerfile
    - frontend/pnpm-workspace.yaml
---

## 1. 核心系统与工具
该项目采用 **pnpm** 作为前后端统一的 JavaScript/TypeScript 包管理器，并通过 **Docker Compose** 进行容器化编排。项目明确指定了 `packageManager` 字段（`pnpm@11.5.2`），利用 Corepack 机制确保开发环境与生产环境使用完全一致的包管理版本。

- **包管理器**: pnpm (v11.5.2)
- **锁定文件**: `pnpm-lock.yaml`
- **运行时**: Node.js (Backend: v22-alpine, Frontend Builder: v18-alpine)
- **部署编排**: Docker Compose

## 2. 关键文件与配置
- **`backend/package.json` / `frontend/package.json`**: 分别定义了后端 API 和前端 Vue 应用的依赖清单。后端依赖包括 `express`, `sequelize`, `mysql2`, `ioredis` 等；前端依赖包括 `vue`, `element-plus`, `axios` 等。
- **`pnpm-lock.yaml`**: 存在于 `backend/` 和 `frontend/` 目录下，用于精确锁定依赖树，确保构建的可重复性。
- **`frontend/pnpm-workspace.yaml`**: 虽然目前仅包含 `allowBuilds` 配置，但表明前端目录具备向 pnpm Workspace 演进的潜力或已预留相关配置入口。
- **`Dockerfile`**: 
  - 后端：通过 `corepack enable pnpm` 启用 pnpm，并使用 `--frozen-lockfile` 参数安装生产依赖。
  - 前端：采用多阶段构建，在 `builder` 阶段安装依赖并打包，最终产物由 `nginx:alpine` 托管。

## 3. 架构与约定
- **依赖隔离**: 前后端拥有独立的 `node_modules` 和锁定文件，互不干扰。
- **生产环境优化**: 
  - 后端 Docker 镜像仅安装 `dependencies` (`--prod`)，排除 `devDependencies`（如 `nodemon`），减小镜像体积。
  - 前端通过多阶段构建，最终镜像不包含 `node_modules` 或构建工具，仅保留静态资源。
- **版本一致性**: 通过在 `package.json` 中声明 `packageManager` 字段，配合 CI/CD 或本地开发时的 Corepack 支持，强制统一工具链版本。

## 4. 开发者规范
- **安装依赖**: 必须使用 `pnpm install`，禁止使用 `npm install` 或 `yarn`，以避免锁定文件冲突。
- **更新依赖**: 修改 `package.json` 后，需重新运行 `pnpm install` 并同步提交更新后的 `pnpm-lock.yaml`。
- **容器化构建**: 生产环境部署应优先使用 `docker-compose up --build`，确保依赖安装过程遵循 Dockerfile 中定义的 `--frozen-lockfile` 约束，防止意外引入未锁定的新版本。