chore: commit oxfmt formatting changes and verify artifacts

openspec/changes/migrate-to-turborepo/design.md

@@ -0,0 +1,112 @@
+## 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 中声明 |