gongxue-base/openspec/changes/archive/2026-07-02-migrate-to-turborepo/proposal.md

Why

当前项目采用平面目录结构（backend/ + frontend/），根 package.json 仅用 cd 脚本串联两个子项目。规划中将新增学生端（student）等应用，现有结构无法支持统一构建编排、共享配置和依赖管理，项目工程化能力成为扩张瓶颈。需要建立标准 monorepo 体系，为多应用并行开发奠定基础。

What Changes

• BREAKING：目录重组 — backend/ → apps/server/（API 服务），frontend/ → apps/admin/（管理后台），预留 apps/student/（学生端）
• 引入 Turborepo 构建编排，定义 turbo.json 流水线
• 根 package.json 改造为 npm workspaces 声明
• 抽取共享 TypeScript 配置到 packages/typescript-config/
• 代码格式化从 Prettier 迁移到 oxfmt
• 前端 Linting 从 ESLint 迁移到 oxlint（后端保留 ESLint，保障 NestJS 规则覆盖）
• Docker Compose 构建上下文路径调整
• 新增统一的根级脚本：dev、build、lint、format

Capabilities

New Capabilities

• monorepo-structure: npm workspaces 驱动的 monorepo 目录结构（apps/ + packages/）
• turborepo-pipeline: Turborepo 构建流水线与缓存
• oxlint-oxfmt-toolchain: 基于 oxlint + oxfmt 的代码质量工具链（前端 oxlint，后端保留 ESLint）

Modified Capabilities

Impact

• 目录结构：所有顶层 backend/、frontend/ 路径引用需更新
• 配置文件：根 package.json、tsconfig（新增共享包）、.gitignore、Dockerfiles、docker-compose.yml
• 开发流程：开发、构建、lint、format 命令从子目录变更到根目录执行
• 无业务代码变更：src/ 下所有业务逻辑保持不变