docs: 全文档合规检查与修正 - 代码示例规范/行数准确性/路径一致性/状态同步

docs/architecture/audit/core-business-audit.md

@@ -12,18 +12,18 @@
 | 维度 | 状态 | 说明 |
 |------|------|------|
 | 模块职责边界 | ⚠️ 部分违规 | homework 混入考试/班级逻辑；grades 混入班级/用户逻辑 |
-| data-access 层职责 | ❌ 普遍违规 | 5 个模块均存在跨模块直接 DB 查询；homework/data-access.ts 混入排名业务逻辑 |
-| actions 层职责 | ⚠️ 部分违规 | exams/homework/questions 的 actions 直接访问 DB；textbooks/grades 的 actions 设计良好 |
+| data-access 层职责 | ❌ 普遍违规 | 5 个模块均存在跨模块直接 DB 查询；homework/data-access.ts 混入排名业务逻辑（已拆分 stats-service.ts） |
+| actions 层职责 | ✅ 已修复 | exams/homework/questions/announcements 的 actions DB 操作已下沉到 data-access（P1-2）；textbooks/grades 的 actions 设计良好 |
 | 组件耦合 | ✅ 基本合规 | 组件层跨模块依赖均为类型导入或 UI 组合，无直接 data-access 调用 |
 | 跨模块依赖 | ⚠️ 存在风险 | 无循环依赖，但 exams→questions、homework→exams、grades→classes 的直接 DB 访问破坏封装 |
-| 文件行数 | ❌ 存在违规 | homework/data-access.ts 1038 行（超 1000 硬上限）；exams/ai-pipeline.ts 912 行、exams/actions.ts 832 行（超 800 建议值） |
+| 文件行数 | ✅ 已修复 | homework/data-access.ts 已拆分（598 行 + stats-service.ts 425 行 + data-access-write.ts 285 行）；exams/ai-pipeline.ts 857 行（超 800 建议值，P1 待拆分） |
 
 ### 关键风险项
 
-1. **homework/data-access.ts 超过 1000 行硬上限**（1038 行）—— 必须拆分
-2. **5 个模块均存在跨模块直接 DB 查询** —— 违反模块封装原则
-3. **exams/homework/questions 的 actions 层混入数据访问逻辑** —— 应只做编排
-4. **homework/data-access.ts 混入排名计算业务逻辑** —— data-access 应只负责数据存取
+1. ~~**homework/data-access.ts 超过 1000 行硬上限**（1038 行）—— 必须拆分~~ ✅ 已拆分
+2. **5 个模块均存在跨模块直接 DB 查询** —— 违反模块封装原则（P1-1 待修复）
+3. ~~**exams/homework/questions 的 actions 层混入数据访问逻辑** —— 应只做编排~~ ✅ 已修复（P1-2）
+4. ~~**homework/data-access.ts 混入排名计算业务逻辑** —— data-access 应只负责数据存取~~ ✅ 已修复（拆分到 stats-service.ts）
 
 ---
 
@@ -81,35 +81,34 @@
 
 | 文件 | 行数 | 限制 | 状态 |
 |------|------|------|------|
-| actions.ts | 832 | ≤800 | ⚠️ 超限 |
-| ai-pipeline.ts | 912 | ≤800 | ⚠️ 超限 |
-| data-access.ts | 339 | ≤800 | ✅ |
+| actions.ts | 691 | ≤800 | ✅（P1-2 后从 832 降至 691） |
+| ai-pipeline.ts | 857 | ≤800 | ⚠️ 超限（P1 待拆分） |
+| data-access.ts | 471 | ≤800 | ✅（P1-2 后从 339 扩展到 471） |
 | types.ts | 31 | 无限制 | ✅ |
 | hooks/use-exam-preview.ts | 295 | ≤500 | ✅ |
 
 #### 模块职责边界
 
 - **职责**：考试全生命周期管理（创建/编辑/预览/发布/删除/复制）+ AI 辅助出题
-- **问题**：`getSubjectsAction`/`getGradesAction` 属于 school 模块职责，被放在 exams/actions.ts 中
+- **问题**：`getSubjectsAction`/`getGradesAction` 属于 school 模块职责，被放在 exams/actions.ts 中（P1-1 待修复）
 
 #### data-access 层问题
 
 | 函数 | 问题 | 严重程度 |
 |------|------|---------|
-| `getExams` | 直接查询 `classes` 表获取教师 gradeIds（第 71-78 行） | 高 |
-| `getExamById` | 直接查询 `classes` 表获取教师 gradeIds（第 155-159 行） | 高 |
-| `persistAiGeneratedExamDraft` | 直接 insert 到 `questions` 表（第 317-326 行） | 高 |
+| `getExams` | 直接查询 `classes` 表获取教师 gradeIds | 高（P1-1 待修复） |
+| `getExamById` | 直接查询 `classes` 表获取教师 gradeIds | 高（P1-1 待修复） |
+| `persistAiGeneratedExamDraft` | 直接 insert 到 `questions` 表 | 高（P1-1 待修复） |
 
-#### actions 层问题
+#### actions 层问题 ✅ 已修复（P1-2）
 
-| 函数 | 问题 | 严重程度 |
-|------|------|---------|
-| `updateExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete`/`db.insert`/`db.update` 操作 examQuestions | 高 |
-| `deleteExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete` | 高 |
-| `duplicateExamAction` | 直接 `db.query.exams.findFirst` + `db.transaction` 内联 insert exams/examQuestions | 高 |
-| `getExamPreviewAction` | 直接 `db.query.exams.findFirst` 查询考试预览数据 | 高 |
-| `getSubjectsAction` | 直接查询 `subjects` 表 —— 跨模块 DB 访问 | 高 |
-| `getGradesAction` | 直接查询 `grades` 表 —— 跨模块 DB 访问 | 高 |
+~~exams/actions.ts 中的 DB 操作已下沉到 data-access~~
+
+**已完成修复**（2026-06-17，commit 84d6636）：
+- 新增 7 个 data-access 函数（updateExam / deleteExam / duplicateExam / getExamPreview 等）
+- actions.ts 从 832 行降至 691 行
+- data-access.ts 从 339 行扩展到 471 行
+- actions 层不再有直接 `db.insert/update/delete`
 
 #### 组件耦合
 
@@ -122,9 +121,9 @@
 
 #### ai-pipeline.ts 问题
 
-- 912 行，超过 800 行建议值
+- 857 行，超过 800 行建议值（原 912 行，已部分优化）
 - 混合了 Zod schema、AI prompt、JSON 解析修复、题目详情解析、并发控制等多种职责
-- 建议拆分为：`ai-schema.ts`（Zod schema）、`ai-prompts.ts`（prompt 常量）、`ai-parser.ts`（JSON 解析修复）、`ai-pipeline.ts`（核心生成逻辑）
+- 建议拆分为：`ai-schema.ts`（Zod schema）、`ai-prompts.ts`（prompt 常量）、`ai-parser.ts`（JSON 解析修复）、`ai-pipeline.ts`（核心生成逻辑）（P1 待处理）
 
 ---
 
@@ -134,49 +133,48 @@
 
 | 文件 | 行数 | 限制 | 状态 |
 |------|------|------|------|
-| data-access.ts | **1038** | ≤1000 硬上限 | ❌ **必须拆分** |
-| actions.ts | 387 | ≤800 | ✅ |
+| data-access.ts | 598 | ≤1000 硬上限 | ✅（P0-2 后从 1038 降至 598） |
+| data-access-write.ts | 285 | ≤800 | ✅（P1-2 新增，10 个写函数） |
+| stats-service.ts | 425 | ≤800 | ✅（P0-2 新增，统计业务逻辑） |
+| actions.ts | 239 | ≤800 | ✅（P1-2 后从 387 降至 239） |
 | schema.ts | 29 | 无限制 | ✅ |
 | types.ts | 186 | 无限制 | ✅ |
 
 #### 模块职责边界
 
 - **职责**：作业全生命周期（创建/发布/作答/批改/分析）
-- **问题**：`getStudentDashboardGrades` 包含班级排名计算逻辑（150+ 行），属于 dashboard 或 grades 模块职责
+- **问题**：`getStudentDashboardGrades` 包含班级排名计算逻辑（已迁移到 stats-service.ts）
 
-#### data-access 层问题（严重）
+#### data-access 层问题（部分修复）
 
 | 函数 | 问题 | 严重程度 |
 |------|------|---------|
-| `getStudentDashboardGrades` | 150+ 行排名计算业务逻辑混入 data-access | 高 |
-| `getHomeworkAssignmentAnalytics` | 145+ 行错误率/错误答案统计业务逻辑混入 data-access | 高 |
-| `getHomeworkAssignments` | 直接查询 `exams` 表（第 167-171 行） | 高 |
-| `getHomeworkAssignmentReviewList` | 直接查询 `exams` 表（第 227-233 行） | 高 |
-| `getHomeworkSubmissions` | 直接查询 `exams` 表（第 349-359 行） | 高 |
-| `getHomeworkAssignmentById` | 直接查询 `exams` 表（第 403-407 行） | 高 |
-| `getStudentHomeworkAssignments` | 直接 join `exams`/`subjects` 表（第 730-731 行） | 高 |
-| `getDemoStudentUser` | 直接查询 `users`/`roles`/`usersToRoles` 表 + 使用 `auth()` 而非 auth-guard | 高 |
-| `getStudentDashboardGrades` | 直接查询 `classEnrollments`/`users` 表 | 高 |
+| ~~`getStudentDashboardGrades`~~ | ~~150+ 行排名计算业务逻辑混入 data-access~~ ✅ 已迁移到 stats-service.ts | ✅ 已修复 |
+| ~~`getHomeworkAssignmentAnalytics`~~ | ~~145+ 行错误率/错误答案统计业务逻辑混入 data-access~~ ✅ 已迁移到 stats-service.ts | ✅ 已修复 |
+| `getHomeworkAssignments` | 直接查询 `exams` 表 | 高（P1-1 待修复） |
+| `getHomeworkAssignmentReviewList` | 直接查询 `exams` 表 | 高（P1-1 待修复） |
+| `getHomeworkSubmissions` | 直接查询 `exams` 表 | 高（P1-1 待修复） |
+| `getHomeworkAssignmentById` | 直接查询 `exams` 表 | 高（P1-1 待修复） |
+| `getStudentHomeworkAssignments` | 直接 join `exams`/`subjects` 表 | 高（P1-1 待修复） |
+| `getDemoStudentUser` | 直接查询 `users`/`roles`/`usersToRoles` 表 + 使用 `auth()` 而非 auth-guard | 高（P1-1 待修复） |
+| `getStudentDashboardGrades` | 直接查询 `classEnrollments`/`users` 表 | 高（P1-1 待修复） |
 
-#### actions 层问题
+#### actions 层问题 ✅ 已修复（P1-2）
 
-| 函数 | 问题 | 严重程度 |
-|------|------|---------|
-| `createHomeworkAssignmentAction` | **157 行**，混合数据访问 + 业务逻辑 + 权限校验 | 高 |
-| 同上 | 直接查询 `classes`/`classSubjectTeachers`/`exams`/`classEnrollments` 表 | 高 |
-| 同上 | 内联 `db.transaction` insert homeworkAssignments/homeworkAssignmentQuestions/homeworkAssignmentTargets | 高 |
-| `startHomeworkSubmissionAction` | 直接 `db.query` + `db.insert` | 高 |
-| `saveHomeworkAnswerAction` | 直接 `db.query` + `db.transaction` | 高 |
-| `submitHomeworkAction` | 直接 `db.query` + `db.update` | 高 |
-| `gradeHomeworkSubmissionAction` | 直接 `db.update` 循环更新 homeworkAnswers | 高 |
+~~homework/actions.ts 中的 DB 操作已下沉到 data-access~~
 
-#### 拆分建议
+**已完成修复**（2026-06-17，commit 84d6636）：
+- 新建 data-access-write.ts（285 行，10 个写函数）
+- actions.ts 从 387 行降至 239 行
+- `createHomeworkAssignmentAction` 等 Action 的 DB 操作全部下沉到 data-access-write.ts
+- actions 层不再有直接 `db.insert/update/delete`
 
-`data-access.ts`（1038 行）建议拆分为：
-- `data-access.ts`：基础 CRUD（getHomeworkAssignments, getHomeworkAssignmentById, getHomeworkSubmissions）
-- `data-access-student.ts`：学生视角查询（getStudentHomeworkAssignments, getStudentHomeworkTakeData, getStudentDashboardGrades）
-- `data-access-analytics.ts`：分析统计（getHomeworkAssignmentAnalytics, getTeacherGradeTrends）
-- `data-access-grading.ts`：批改相关（getHomeworkSubmissionDetails, getHomeworkAssignmentReviewList）
+#### 拆分结果 ✅ 已完成
+
+`data-access.ts`（原 1038 行）已拆分为：
+- `data-access.ts`（598 行）：基础 CRUD + 查询
+- `data-access-write.ts`（285 行）：写操作（10 个写函数）
+- `stats-service.ts`（425 行）：统计业务逻辑（排名计算、错误率统计等）
 
 ---
 
@@ -186,30 +184,33 @@
 
 | 文件 | 行数 | 限制 | 状态 |
 |------|------|------|------|
-| actions.ts | 294 | ≤800 | ✅ |
-| data-access.ts | 129 | ≤800 | ✅ |
+| actions.ts | 149 | ≤800 | ✅（P1-2 后从 294 降至 149） |
+| data-access.ts | 260 | ≤800 | ✅（P1-2 后从 129 扩展到 260） |
 | schema.ts | 18 | 无限制 | ✅ |
 | types.ts | 34 | 无限制 | ✅ |
 
 #### 模块职责边界
 
 - **职责**：题库管理（题目 CRUD、知识点关联、题型支持）
-- **问题**：`getKnowledgePointOptionsAction` 查询 textbooks 模块的表，属于 textbooks 模块职责
+- **问题**：`getKnowledgePointOptionsAction` 查询 textbooks 模块的表，属于 textbooks 模块职责（P1-1 待修复）
 
-#### data-access 层问题
+#### data-access 层问题 ✅ 已修复（P1-2）
 
 - ✅ 仅访问 `questions` 和 `questionsToKnowledgePoints` 表，无跨模块 DB 访问
-- ❌ **缺失写操作函数**：`insertQuestionWithRelations`、`deleteQuestionRecursive` 等 data-access 函数被错误地放在 actions.ts 中
+- ✅ **写操作函数已补全**：`insertQuestionWithRelations`、`deleteQuestionRecursive` 等 data-access 函数已从 actions.ts 迁移到 data-access.ts（data-access.ts 从 129 行扩展到 260 行）
 
-#### actions 层问题
+#### actions 层问题 ✅ 已修复（P1-2）
 
-| 函数 | 问题 | 严重程度 |
-|------|------|---------|
-| `createNestedQuestion` | 内联 `db.transaction` + 调用 `insertQuestionWithRelations`（data-access 函数错放在 actions） | 高 |
-| `updateQuestionAction` | 内联 `db.transaction` 做 update/delete/insert | 高 |
-| `deleteQuestionAction` | 内联 `db.transaction` + 调用 `deleteQuestionRecursive`（data-access 函数错放在 actions） | 高 |
-| `getKnowledgePointOptionsAction` | 直接查询 `knowledgePoints`/`chapters`/`textbooks` 表 —— 跨模块 DB 访问 | 高 |
-| `getQuestionsAction` | ✅ 正确委托给 data-access.getQuestions | ✅ |
+~~questions/actions.ts 中的 DB 操作已下沉到 data-access~~
+
+**已完成修复**（2026-06-17，commit 84d6636）：
+- 新增 4 个 data-access 函数（insertQuestionWithRelations / deleteQuestionRecursive 等）
+- actions.ts 从 294 行降至 149 行
+- `createNestedQuestion` / `updateQuestionAction` / `deleteQuestionAction` 的 DB 操作全部下沉
+- actions 层不再有直接 `db.transaction`
+
+**剩余问题**：
+- `getKnowledgePointOptionsAction` 仍直接查询 `knowledgePoints`/`chapters`/`textbooks` 表 —— 跨模块 DB 访问（P1-1 待修复）
 
 #### 组件耦合
 
@@ -348,10 +349,11 @@
 
 ### 5.1 高优先级（P0）
 
-1. **拆分 homework/data-access.ts**（1038 行 → 4 个文件）
-   - 按职责拆分为 data-access.ts / data-access-student.ts / data-access-analytics.ts / data-access-grading.ts
+1. ~~**拆分 homework/data-access.ts**（1038 行 → 4 个文件）~~ ✅ 已完成
+   - ~~按职责拆分为 data-access.ts / data-access-student.ts / data-access-analytics.ts / data-access-grading.ts~~
+   - 实际拆分为 data-access.ts（598 行）+ data-access-write.ts（285 行）+ stats-service.ts（425 行）
 
-2. **消除跨模块直接 DB 访问**
+2. **消除跨模块直接 DB 访问**（P1-1 待修复）
    - 在 classes/data-access 暴露 `getClassGradeIdsByClassIds`、`getClassStudentsByClassId`、`getActiveClassStudents` 等函数
    - 在 exams/data-access 暴露 `getExamForHomeworkCreation`（含 questions 关联）
    - 在 school/data-access 暴露 `getSubjectOptions`、`getGradeOptions`
@@ -359,41 +361,41 @@
    - 在 textbooks/data-access 暴露 `getKnowledgePointOptions`
    - 在 questions/data-access 暴露 `insertQuestionWithRelations`、`deleteQuestionRecursive`
 
-3. **将 exams/actions.ts 中的 DB 操作下沉到 data-access**
-   - `updateExamAction`、`deleteExamAction`、`duplicateExamAction`、`getExamPreviewAction` 的 DB 操作移至 data-access
-   - 将 `getSubjectsAction`/`getGradesAction` 移至 school 模块或改为调用 school/data-access
+3. ~~**将 exams/actions.ts 中的 DB 操作下沉到 data-access**~~ ✅ 已完成（P1-2）
+   - ~~`updateExamAction`、`deleteExamAction`、`duplicateExamAction`、`getExamPreviewAction` 的 DB 操作移至 data-access~~
+   - ~~将 `getSubjectsAction`/`getGradesAction` 移至 school 模块或改为调用 school/data-access~~（P1-1 待修复）
 
-4. **将 homework/actions.ts 中的 DB 操作下沉到 data-access**
-   - `createHomeworkAssignmentAction`（157 行）拆分为：data-access 函数 + action 编排
-   - 其他 action 的 DB 操作全部移至 data-access
+4. ~~**将 homework/actions.ts 中的 DB 操作下沉到 data-access**~~ ✅ 已完成（P1-2）
+   - ~~`createHomeworkAssignmentAction`（157 行）拆分为：data-access 函数 + action 编排~~
+   - ~~其他 action 的 DB 操作全部移至 data-access~~
 
-5. **将 questions/actions.ts 中的 DB 操作下沉到 data-access**
-   - `insertQuestionWithRelations`、`deleteQuestionRecursive` 移至 data-access
-   - `getKnowledgePointOptionsAction` 改为调用 textbooks/data-access
+5. ~~**将 questions/actions.ts 中的 DB 操作下沉到 data-access**~~ ✅ 已完成（P1-2）
+   - ~~`insertQuestionWithRelations`、`deleteQuestionRecursive` 移至 data-access~~
+   - ~~`getKnowledgePointOptionsAction` 改为调用 textbooks/data-access~~（P1-1 待修复）
 
 ### 5.2 中优先级（P1）
 
-6. **拆分 exams/ai-pipeline.ts**（912 行 → 4 个文件）
+6. **拆分 exams/ai-pipeline.ts**（857 行 → 4 个文件）
    - ai-schema.ts（Zod schema）、ai-prompts.ts（prompt 常量）、ai-parser.ts（JSON 解析修复）、ai-pipeline.ts（核心生成逻辑）
 
-7. **将 homework/data-access.ts 中的业务逻辑提取到独立服务层**
-   - `getStudentDashboardGrades` 的排名计算逻辑提取到 `services/ranking-service.ts`
-   - `getHomeworkAssignmentAnalytics` 的错误率统计逻辑提取到 `services/analytics-service.ts`
+7. ~~**将 homework/data-access.ts 中的业务逻辑提取到独立服务层**~~ ✅ 已完成
+   - ~~`getStudentDashboardGrades` 的排名计算逻辑提取到 `services/ranking-service.ts`~~ → 实际提取到 `stats-service.ts`
+   - ~~`getHomeworkAssignmentAnalytics` 的错误率统计逻辑提取到 `services/analytics-service.ts`~~ → 实际提取到 `stats-service.ts`
 
-8. **将 grades/data-access.ts 中的统计计算逻辑提取到独立服务层**
+8. **将 grades/data-access.ts 中的统计计算逻辑提取到独立服务层**（P1 待处理）
    - `getClassGradeStats` 的统计计算提取到 `services/stats-service.ts`
    - `getGradeDistribution` 的分桶逻辑提取到 `services/distribution-service.ts`
 
-9. **减少组件 props 数量**
+9. **减少组件 props 数量**（P2 待处理）
    - `ExamAssembly`（10 props）和 `ExamPreviewQuestionEditor`（10 props）应考虑使用 Context 或组合模式减少 props
 
 ### 5.3 低优先级（P2）
 
-10. **统一 auth 调用方式**
+10. **统一 auth 调用方式**（P2 待处理）
     - `homework/data-access.ts` 的 `getDemoStudentUser` 使用 `auth()` 而非 `auth-guard.getAuthContext()`，应统一
 
-11. **补全 questions/data-access.ts 的写操作**
-    - 当前 data-access 仅有 `getQuestions`，所有写操作错放在 actions.ts
+11. ~~**补全 questions/data-access.ts 的写操作**~~ ✅ 已完成（P1-2）
+    - ~~当前 data-access 仅有 `getQuestions`，所有写操作错放在 actions.ts~~ → 写操作已下沉到 data-access
 
 ---