5.2 KiB
5.2 KiB
Context
当前项目为双应用平面结构：backend/（NestJS + TypeORM）和 frontend/（React 19 + Vite），通过 docker-compose.yml 编排部署。根 package.json 仅包含两个 cd 子目录的脚本，无统一构建编排能力。
随着业务扩展规划（学生端 apps/student/ 等新应用），当前结构面临以下问题：
- 无共享配置机制，前后端各自维护 ESLint/TypeScript 配置
- 无构建缓存和并行能力，CI 时间随应用增加线性增长
- 新增应用无标准目录约定，结构逐渐混乱
Goals / Non-Goals
Goals:
- 建立标准 Turborepo monorepo 目录结构（apps/ + packages/）
- 引入 Turborepo 构建流水线与缓存，支持并行构建
- npm workspaces 统一依赖管理
- 抽取共享 TypeScript 配置到独立 package
- 代码格式化迁移到 oxfmt（统一）
- 前端 Linting 迁移到 oxlint（更快），后端保留 ESLint（保障 NestJS 覆盖）
- Docker Compose 构建上下文适配新目录结构
Non-Goals:
- 不拆分后端微服务
- 不引入 pnpm/yarn 包管理器
- 不重构业务代码逻辑（src/ 零变更）
- 不修改 Docker Compose 服务编排逻辑
- 暂不抽取 shared-types 包
Decisions
1. 选择 Turborepo 而非 Nx/Lerna
| 维度 | Turborepo | Nx | Lerna |
|---|---|---|---|
| 构建缓存 | ✅ 内置（内容哈希） | ✅ 内置 | ⚠️ 需插件 |
| 并行执行 | ✅ 自动拓扑排序 | ✅ 自动 | ⚠️ 手动配置 |
| 配置复杂度 | 低（单一 turbo.json） | 中（nx.json + project.json） | 低 |
| 生态 | Vercel 维护，与 Vite 天然契合 | 功能最强但重 | 社区为主 |
选择 Turborepo：项目前端使用 Vite（同属 Vercel 生态），配置简洁，满足当前规模需求且不过度设计。
2. 选择 npm workspaces（用户指定）
用户要求沿用 npm。npm workspaces 自 v8+ 已成熟，支持 --workspace 标志，与 Turborepo 完全兼容。
3. 目录结构选择：apps/ + packages/
采用 Turborepo 官方推荐结构：
gongxue-base/
├── apps/
│ ├── server/ # ← 当前 backend/ 移入（API 服务）
│ ├── admin/ # ← 当前 frontend/ 移入（管理后台）
│ └── student/ # 未来：学生端
├── packages/
│ └── typescript-config/ # 共享 TS 配置
├── package.json # workspaces 声明 + 根脚本
├── turbo.json # Turborepo 流水线
├── .oxfmtrc.json # oxfmt 全局配置
├── oxlint.config.ts # oxlint 全局配置
└── docker-compose.yml # 调整构建 context
4. oxlint / oxfmt 工具链策略
oxfmt：统一替换 Prettier。oxfmt 与 Prettier 格式输出高度兼容，配置项映射简单。.oxfmtrc.json 放在根目录。
oxlint：采用混合策略：
- 前端（apps/admin）：全面切换 oxlint。现有规则映射：
typescript-eslint→ oxlint 内置 TypeScript 规则 ✅react-hooks/rules-of-hooks→ oxlint 内置 ✅react-hooks/exhaustive-deps→ ⚠️ oxlint 不支持，在 oxlint.config.ts 中禁用对应检查，接受 IDE 级补充react-refresh→ ❌ 无等效规则，损失较小（仅 HMR 时的 export 检查）
- 后端（apps/server）：保留 ESLint。NestJS 特有的装饰器类型检查和依赖注入规则（
@typescript-eslint/no-unsafe-*系列）在 oxlint 中无等效覆盖，贸然切换风险较高。
5. 共享 TypeScript 配置设计
packages/typescript-config/ 提供三个预设：
base.json— 通用 compilerOptions（strictNullChecks、skipLibCheck、forceConsistentCasingInFileNames、esModuleInterop等）nestjs.json— 继承 base + NestJS 特有（experimentalDecorators、emitDecoratorMetadata、declaration）react-vite.json— 继承 base + 前端特有（jsx: react-jsx、moduleResolution: bundler）
6. Turbo 流水线设计
{
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**"]
},
"dev": {
"cache": false,
"persistent": true
},
"lint": { "dependsOn": ["^build"] },
"test": { "dependsOn": ["build"] },
"format": { "cache": false },
"typecheck": { "dependsOn": ["^build"] }
}
}
Risks / Trade-offs
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| 目录迁移导致所有路径引用失效 | import 路径、Dockerfile、CI 脚本全部需更新 | tasks 中拆分独立的"目录迁移"步骤，逐项验证 |
| oxlint 覆盖不足导致部分规则缺失 | exhaustive-deps、react-refresh 规则丢失 |
明确记录缺失规则，依赖 TypeScript compiler 和 code review 兜底 |
| npm workspaces hoisting 行为变化 | 子项目可能访问到 hoisted 的不兼容版本 | Turborepo 严格模式下按 workspace 隔离；迁移后全量测试 |
| Docker 构建 context 路径变更 | docker-compose.yml 中 build: ./backend 需改为 build: ./apps/server |
迁移后 docker compose build 验证 |
| 根 node_modules 现有依赖冲突 | @fission-ai/openspec 与子项目依赖可能 hoisting 冲突 |
openspec 保留在根，子项目依赖在各自 workspace 中声明 |