gongxue-base/docs/superpowers/specs/2026-07-02-migrate-to-turborepo-design.md

comet_change, role, canonical_spec, archived-with, status

comet_change	role	canonical_spec	archived-with	status
migrate-to-turborepo	technical-design	openspec	2026-07-02-migrate-to-turborepo	final

Migrate to Turborepo Monorepo — Technical Design

Architecture Overview

gongxue-base/
├── apps/
│   ├── server/                 # ← git mv backend → apps/server (NestJS API)
│   ├── admin/                  # ← git mv frontend → apps/admin (React + Vite)
│   └── student/                # 未来：学生端
├── packages/
│   └── typescript-config/      # 共享 TS 配置：base / nestjs / react-vite
├── package.json                # npm workspaces + turbo 根脚本
├── turbo.json                  # Turborepo 流水线
├── .oxfmtrc.json               # oxfmt 全局配置
├── oxlint.config.ts            # oxlint 全局配置（admin 前端）
└── docker-compose.yml          # 调整 build.context 路径

Key Decisions

1. File Migration: git mv

node_modules/ 从未被 Git 追踪，因此 git mv backend apps/server 和 git mv frontend apps/admin 可以干净执行，完整保留文件历史。

2. Package Manager: npm workspaces

用户指定沿用 npm。根 package.json 声明 workspaces: ["apps/*", "packages/*"]，所有根脚本委托 turbo run 执行。

3. Build Orchestration: Turborepo

turbo.json 定义六条流水线：

Task	配置
build	dependsOn: ["^build"], outputs: dist/**
dev	cache: false, persistent: true
lint	无特殊配置，各 workspace 自行定义工具
test	无特殊配置
format	cache: false (oxfmt)
typecheck	dependsOn: ["^build"]

4. Toolchain: oxfmt + oxlint (mixed)

• oxfmt：根目录 .oxfmtrc.json，映射 Prettier 配置 { singleQuote: true, trailingComma: "all" }
• oxlint：仅用于 apps/admin，覆盖 TypeScript + React 规则。exhaustive-deps 和 react-refresh 由 TypeScript compiler + code review 兜底
• ESLint：apps/server 保留，移除 Prettier 集成。保障 NestJS 装饰器类型检查

所有 workspace 统一使用 lint 脚本名，Turborepo 在 turbo run lint 时并行调度。

5. Shared TypeScript Config

@gongxue/typescript-config 包提供三个预设：

预设	继承	用途
base.json	—	通用选项：ES2023、strictNullChecks、skipLibCheck
nestjs.json	base	NestJS：nodenext module、experimentalDecorators、declaration
react-vite.json	base	Vite + React：bundler resolution、jsx: react-jsx、noEmit

TypeScript 版本统一为 ~6.0.2（从 server 5.7→6.0 和 admin 6.0 对齐）。

6. Docker Compose

容器名 dorm_billing_backend / dorm_billing_frontend 保持不变，仅调整 build.context：

• backend: build: ./apps/server
• frontend: build: ./apps/admin

Data Flow

npm run dev (根)
    │
    ▼
turbo run dev
    │
    ├──▶ apps/server (NestJS, :3003)   ← ESLint, @gongxue/typescript-config/nestjs
    └──▶ apps/admin (Vite, :3002)      ← oxlint, @gongxue/typescript-config/react-vite
              │
              ▼ /api proxy → localhost:3003

Testing Strategy

Core Verification Chain

1. npm install — 所有 workspace 依赖正确安装，hoisting 无冲突
2. npm run build — server + admin 构建通过
3. npm run lint — server ESLint + admin oxlint 通过
4. npm run format -- --check — oxfmt 格式化检查通过
5. npm run test --workspace=apps/server — NestJS Jest 测试通过

Runtime Verification

• npm run dev → server :3003 + admin :3002 并行启动
• admin Vite 代理 /api → localhost:3003 正常工作

Docker Verification

• docker compose build — 所有镜像构建成功
• docker compose up — 所有服务启动并响应

Risks & Mitigations

Risk	Impact	Mitigation
git mv 后路径引用失效	docker-compose、tsconfig extends、scripts	逐文件验证，每步 commit
oxlint 规则覆盖不全	exhaustive-deps、react-refresh 缺失	TS compiler + code review 兜底，明确文档化
TS 6.x + NestJS 生态兼容	ts-jest、ts-node 可能报错	迁移后立即验证 build + test
npm hoisting 行为变化	子项目可能拿到不兼容版本	重新 install 后逐 workspace 验证