## 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 流水线设计

```json
{
  "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 中声明 |