优化首页报表
This commit is contained in:
eafonyang
@@ -6,39 +6,51 @@ scope:
|
||||
- '**'
|
||||
source_files:
|
||||
- backend/package.json
|
||||
- backend/pnpm-lock.yaml
|
||||
- frontend/package.json
|
||||
- frontend/pnpm-workspace.yaml
|
||||
- frontend/.npmrc
|
||||
- backend/pnpm-lock.yaml
|
||||
- frontend/packages/axios/package.json
|
||||
- frontend/packages/hooks/package.json
|
||||
---
|
||||
|
||||
## 系统概览
|
||||
|
||||
本项目采用 pnpm 作为统一的包管理器，通过 Monorepo 工作区（workspace）组织前后端代码，并使用 pnpm-lock.yaml 锁定依赖版本。前端基于 pnpm workspace 将公共能力拆分为多个内部包，后端为独立单包结构。
|
||||
本项目采用 **pnpm** 作为统一的 Node.js 包管理器，在前后端两个独立子项目中使用。前端基于 pnpm workspace 构建 monorepo，后端为单包结构；两者均通过 `pnpm-lock.yaml` 锁定依赖版本，并使用国内 npm 镜像加速安装。
|
||||
|
||||
## 关键文件与位置
|
||||
|
||||
- backend/package.json — 后端 API 服务依赖声明（Express、Sequelize、MySQL2、AWS S3 SDK、Redis 等）
|
||||
- frontend/package.json — 前端主应用依赖声明（Vue3、NaiveUI、Vite、Pinia 等），并通过 workspace:* 引用内部包
|
||||
- frontend/pnpm-workspace.yaml — 定义工作区包路径 packages/* 及 hoist/link 行为
|
||||
- frontend/.npmrc — 全局 npm 镜像源指向 https://registry.npmmirror.com/
|
||||
- backend/pnpm-lock.yaml / frontend/pnpm-lock.yaml — 精确锁定的依赖树快照
|
||||
- frontend/packages/*/package.json — 内部子包（如 @sa/axios、@sa/hooks、@sa/utils 等）的依赖声明
|
||||
- **后端依赖声明**: `backend/package.json`、`backend/pnpm-lock.yaml`
|
||||
- **前端根工作区**: `frontend/package.json`、`frontend/pnpm-workspace.yaml`、`frontend/pnpm-lock.yaml`
|
||||
- **镜像源配置**: `frontend/.npmrc`（registry 指向 npmmirror）
|
||||
- **前端内部子包**: `frontend/packages/axios/package.json`、`frontend/packages/hooks/package.json`、`frontend/packages/color/package.json`、`frontend/packages/materials/package.json`、`frontend/packages/utils/package.json`、`frontend/packages/scripts/package.json`、`frontend/packages/uno-preset/package.json`
|
||||
|
||||
## 架构与约定
|
||||
|
||||
1. 统一包管理器：根级及各子目录均使用 pnpm，package.json 中显式声明 packageManager: "pnpm@11.5.2"，确保团队与 CI 环境一致性。
|
||||
2. Monorepo 工作区：前端通过 pnpm-workspace.yaml 将 packages/* 纳入同一工作区，配合 shamefullyHoist: true、linkWorkspacePackages: true 实现依赖提升与工作区包软链接。
|
||||
3. 内部包发布模式：前端将通用能力（axios 封装、颜色工具、hooks、UnoCSS 预设等）抽取为 @sa/* 命名空间包，通过 workspace:* 在应用与子包间共享，避免重复安装。
|
||||
4. 镜像源：.npmrc 将默认 registry 替换为国内 npmmirror，加速依赖下载；未配置私有仓库或 .npmrc scope 映射，所有第三方包均来自公开镜像。
|
||||
5. 版本策略：后端生产依赖普遍使用 ^ 语义化范围（如 express ^4.21、sequelize ^6.37），由 lockfile 固定实际解析版本。前端内部包与核心库多使用精确版本号（如 vue 3.5.34、pinia 3.0.4），减少升级不确定性。
|
||||
6. Node 版本约束：前端 engines.node >= 20.19.0、engines.pnpm >= 10.5.0，后端 lockfile 中部分包要求 Node ≥ 18/20，整体以 Node 20+ 为目标运行环境。
|
||||
### 1. 包管理器与版本锁定
|
||||
- 统一使用 pnpm，后端 `package.json` 中显式声明 `"packageManager": "pnpm@11.5.2"`，确保团队与 CI 环境一致。
|
||||
- 前后端均提交 `pnpm-lock.yaml`（lockfileVersion 9.0），禁止随意升级依赖，保证可重现构建。
|
||||
|
||||
### 2. 前端 Monorepo 工作区
|
||||
- `pnpm-workspace.yaml` 将 `packages/*` 纳入工作区，启用 `shamefullyHoist: true`、`linkWorkspacePackages: true`，使子包间以符号链接方式共享依赖，避免重复安装。
|
||||
- 子包之间通过 `workspace:*` 协议互相引用（如 `@sa/axios` 依赖 `@sa/utils`），实现内聚的 UI 工具库复用。
|
||||
- 子包通过 `exports` + `typesVersions` 暴露 TypeScript 入口，对外提供类型安全的 API。
|
||||
|
||||
### 3. 镜像源与私有仓库
|
||||
- `frontend/.npmrc` 全局设置 `registry=https://registry.npmmirror.com/`，所有包从国内镜像拉取，提升安装速度。
|
||||
- 未发现 `.npmrc` 中的 `@scope:registry` 或 `authToken` 等私有仓库配置，当前未接入私有 npm 仓库。
|
||||
|
||||
### 4. 引擎与脚本约束
|
||||
- 前端 `engines.node >= 20.19.0`、`engines.pnpm >= 10.5.0`，配合 `simple-git-hooks` 在 pre-commit 阶段执行 `typecheck && lint && fmt`，在提交前校验依赖与代码质量。
|
||||
- 后端仅提供 `start` / `dev`（nodemon）脚本，无额外构建步骤。
|
||||
|
||||
## 开发者应遵循的规则
|
||||
|
||||
- 新增依赖：在后端 backend/package.json 或前端 frontend/package.json 中添加，不要手动编辑 pnpm-lock.yaml；提交前确保已生成最新 lockfile。
|
||||
- 内部包变更：修改 packages/* 下任意子包后，重新执行 pnpm install 使工作区软链接生效；如需对外发布，需更新对应包的 version 字段。
|
||||
- 镜像源切换：若需接入私有 npm 仓库，应在 .npmrc 中追加 @scope:registry= 或全局 registry= 配置，并在 CI 环境变量中注入认证 token。
|
||||
- 版本升级：优先使用 pnpm update --latest 或脚本 pnpm sa update-pkg（前端提供）进行批量升级，再审查 diff 并更新 lockfile。
|
||||
- Node/pnpm 版本：本地开发需满足 node >= 20.19.0、pnpm >= 10.5.0，建议使用 nvm/corepack 自动匹配。
|
||||
1. **统一使用 pnpm**：新增依赖一律通过 `pnpm add [-D] <pkg>` 安装，不要手动编辑 `node_modules` 或使用 npm/yarn。
|
||||
2. **不直接修改 lock 文件**：依赖升级通过 `pnpm update` 或 `pnpm up` 触发，由 pnpm 生成新的 `pnpm-lock.yaml`。
|
||||
3. **Monorepo 子包规范**：
|
||||
- 新包放在 `frontend/packages/<name>/`，并在其 `package.json` 中声明 `exports` 和 `typesVersions`。
|
||||
- 子包间依赖一律使用 `workspace:*` 协议，禁止写死版本号。
|
||||
4. **镜像源不可绕过**：保持 `.npmrc` 中的 npmmirror 配置不变；如需引入私有包，应在 `.npmrc` 中追加对应 scope 的 registry 与 token。
|
||||
5. **Node/pnpm 版本对齐**：本地 Node 需满足 `>=20.19.0`，pnpm 需 `>=10.5.0`，建议使用 nvm 管理以避免版本漂移。
|
||||
6. **后端依赖精简**：仅保留运行时必需依赖到 `dependencies`，开发期工具（如 nodemon）放入 `devDependencies`，避免污染生产镜像。
|
||||
|
||||
Reference in New Issue
Block a user