# 后端模块规范核查报告 v2

> 核查日期：2026-06-18
> 核查范围：`src/modules/` 下所有后端 `.ts` 文件
> 核查依据：
> - `.trae/rules/project_rules.md` 项目规则
> - `docs/standards/coding-standards.md` 编码规范
> - `docs/architecture/004_architecture_impact_map.md` 架构影响地图
> - Vercel React Best Practices 性能优化规则
> - v1 报告 `bugs/back_bug.md`（对照修复状态）
>
> 本报告相比 v1 的核心变化：
> - 对每个问题标注 **修复状态**（已修复/未修复/部分修复/新问题）
> - 汇总 v1→v2 的修复进度
> - 列出 v2 新发现的问题

---

## 目录

- [一、v1→v2 修复进度总览](#一v1v2-修复进度总览)
- [二、v2 当前问题汇总](#二v2-当前问题汇总)
- [三、仍需优先修复的问题](#三仍需优先修复的问题)
- [四、按模块详细核查](#四按模块详细核查)
- [五、v2 新发现问题清单](#五v2-新发现问题清单)
- [六、架构文档同步提醒](#六架构文档同步提醒)

---

## 一、v1→v2 修复进度总览

### 1.1 整体修复率

| 指标 | v1 问题数 | 已修复 | 部分修复 | 未修复 | 修复率 |
|------|----------|--------|----------|--------|--------|
| 数量 | 129 | 90 | 12 | 27 | 70% 已修复 + 9% 部分修复 |
| P0 | 14 | 14 | 0 | 0 | **100%** |
| P1 | 60 | 39 | 7 | 14 | 65% + 12% |
| P2 | 55 | 37 | 5 | 13 | 67% + 9% |

### 1.2 按模块修复率

| 模块 | v1 问题数 | 已修复 | 部分修复 | 未修复 | 修复率 |
|------|----------|--------|----------|--------|--------|
| homework | 6 | 6 | 0 | 0 | **100%** |
| parent | 3 | 3 | 0 | 0 | **100%** |
| proctoring | 9 | 9 | 0 | 0 | **100%** |
| settings | 9 | 9 | 0 | 0 | **100%** |
| dashboard | 0 | - | - | - | 标杆模块 |
| grades | 8 | 7 | 1 | 0 | 88% |
| questions | 5 | 4 | 0 | 1 | 80% |
| users | 7 | 6 | 0 | 1 | 86% |
| exams | 7 | 5 | 1 | 1 | 71% |
| messaging | 7 | 5 | 0 | 2 | 71% |
| notifications | 7 | 5 | 0 | 2 | 71% |
| audit | 5 | 2 | 0 | 3 | 40% |
| textbooks | 5 | 2 | 1 | 2 | 40% |
| classes | 10 | 7 | 2 | 1 | 70% |
| announcements | 6 | 5 | 1 | 0 | 83% |
| school | 3 | 2 | 0 | 1 | 67% |
| scheduling | 6 | 5 | 1 | 0 | 83% |
| attendance | 1 | 1 | 0 | 0 | 100% |
| course-plans | 3 | 1 | 1 | 1 | 33% |
| elective | 7 | 6 | 1 | 0 | 86% |
| diagnostic | 8 | 7 | 0 | 1 | 88% |
| files | 5 | 3 | 1 | 1 | 60% |
| layout | 2 | 0 | 0 | 2 | 0% |

### 1.3 P0 问题修复情况（全部已修复）

| 编号 | v1 P0 问题 | 修复状态 |
|------|-----------|---------|
| P0-1 | exams/data-access.ts persistAiGeneratedExamDraft 直写 questions 表 | ✅ 已修复：改用 createQuestionWithRelations |
| P0-2 | exams/data-access.ts getExams 等直查 classes 表 | ✅ 已修复：改用 getClassGradeIdsByClassIds |
| P0-3 | questions/schema.ts z.any() | ✅ 已修复：改为 z.unknown() |
| P0-4 | questions/actions.ts 未返回 ActionState | ✅ 已修复：包装为 ActionState<T> |
| P0-5 | textbooks 无 Zod 验证 + 14 处 as 断言 | ⚠️ 部分修复：as 断言已清理，但 Zod 验证仍未添加 |
| P0-6 | grades N+1 查询 | ✅ 已修复：改为 inArray 批量查询 + Map 分组 |
| P0-7 | classes 跨模块直查 homework/exams 表 | ✅ 已修复：改用 homework/data-access-classes |
| P0-8 | school actions 层直接 DB 操作 | ✅ 已修复：DB 操作下沉到 data-access |
| P0-9 | proctoring actions 层直接 DB 操作 | ✅ 已修复：下沉到 data-access |
| P0-10 | messaging↔notifications 循环依赖 | ✅ 已修复：表所有权移交 notifications |
| P0-11 | notifications/in-app-channel.ts 非法 as 断言 | ✅ 已修复：新增 mapPayloadTypeToNotificationType |
| P0-12 | users 硬编码弱密码 "123456" | ✅ 已修复：改用 randomBytes 生成 |
| P0-13 | users/updateUserProfile 绕过权限 | ✅ 已修复：改用 requirePermission + Zod + ActionState |
| P0-14 | scheduling 4 个函数缺返回类型 | ✅ 已修复：已添加返回类型标注 |

---

## 二、v2 当前问题汇总

### 2.1 按严重程度统计（v2 当前状态）

| 严重程度 | 未修复 v1 问题 | 部分修复 v1 问题 | v2 新发现问题 | 合计 |
|----------|---------------|------------------|--------------|------|
| P0 | 0 | 1（textbooks Zod） | 0 | 1 |
| P1 | 14 | 7 | 16 | 37 |
| P2 | 13 | 5 | 25 | 43 |
| **合计** | **27** | **12** | **41** | **80** |

### 2.2 按问题类别统计（v2 当前状态）

| 问题类别 | 数量 | 主要分布 |
|---------|------|---------|
| 架构违规 | 8 | 跨模块直查 DB（exams→school、questions→textbooks、classes→scheduling、messaging→classes、elective→school/users） |
| TS 规范 | 35 | as 断言、缺返回类型标注、隐式 any[]、非空断言 |
| Server Action 规范 | 6 | textbooks 无 Zod、notifications 无 Zod、school 用 parse 非 safeParse、course-plans 缺 revalidatePath |
| 性能 | 15 | 串行查询未并行化、循环内串行 await、未用 React.cache()、隐式 any[] |
| 代码质量 | 12 | try-catch 吞错误、重复 try/catch、死代码、重复代码 |
| 命名规范 | 3 | 布尔变量前缀、函数命名不一致 |
| 数据一致性 | 4 | elective selectCourse/dropCourse 缺事务 |
| 文件行数 | 2 | exams/ai-pipeline.ts 916 行、classes/data-access.ts 866 行 |

---

## 三、仍需优先修复的问题

### 3.1 P0 级别（立即修复）

#### P0-1：textbooks 模块仍无 Zod 验证（v1 未修复）

- **文件**：`src/modules/textbooks/actions.ts`
- **行号**：54-281（所有 Action）
- **问题**：v1 报告的 P0 问题"actions.ts 完全无 Zod 验证"未修复。所有 Action 仍使用手动 `if` 校验，textbooks 模块甚至没有 schema.ts 文件
- **修复建议**：新建 `textbooks/schema.ts`，定义 `CreateTextbookSchema`、`UpdateTextbookSchema`、`CreateChapterSchema`、`CreateKnowledgePointSchema` 等 Zod schema，所有 Action 改用 `schema.safeParse()`

### 3.2 P1 级别（尽快修复）

#### P1-1：exams/data-access.ts 直接查询 school 模块表（v1 未修复）

- **文件**：`src/modules/exams/data-access.ts`
- **行号**：2, 208-228, 519-524, 529-534
- **问题**：`resolveSubjectGradeNames`、`getExamSubjects`、`getExamGrades` 仍直接查询 `subjects`/`grades` 表（school 模块）
- **修复建议**：在 school 模块暴露 `getGradeOptions()`、`getSubjectNameById(id)`、`getGradeNameById(id)` 接口

#### P1-2：questions/data-access.ts 直接查询 textbooks 模块表（v1 未修复）

- **文件**：`src/modules/questions/data-access.ts`
- **行号**：4, 266-299
- **问题**：`getKnowledgePointOptions` 仍直接 LEFT JOIN 查询 `knowledgePoints`、`chapters`、`textbooks` 三张表
- **修复建议**：在 textbooks 模块暴露 `getKnowledgePointOptionsForQuestions()` 接口

#### P1-3：classes/data-access-schedule.ts 直接查询 classSchedule 表（v1 未修复）

- **文件**：`src/modules/classes/data-access-schedule.ts`
- **行号**：7-11, 31-46, 73-86
- **问题**：仍直接导入并查询 `classSchedule` 表（scheduling 模块的表）
- **修复建议**：在 scheduling 模块暴露只读查询函数 `getClassScheduleByClassIds`

#### P1-4：messaging/data-access.ts getRecipients 直接 JOIN 跨模块表（v1 未修复）

- **文件**：`src/modules/messaging/data-access.ts`
- **行号**：26-27, 173-188
- **问题**：`getRecipients` 直接 import 并 JOIN `classEnrollments`、`classes` 表
- **修复建议**：通过 classes 模块暴露 `getStudentIdsByClassIds`、`getStudentIdsByGradeIds` 接口

#### P1-5：notifications/actions.ts 参数未用 Zod 验证（v1 未修复）

- **文件**：`src/modules/notifications/actions.ts`
- **行号**：28-50, 60-110
- **问题**：`sendNotificationAction` 和 `sendClassNotificationAction` 仅使用 TypeScript 类型标注和手动 if 检查
- **修复建议**：新增 `NotificationPayloadSchema` 和 `ClassNotificationSchema`

#### P1-6：textbooks/actions.ts 本地定义 ActionState 类型（v1 未修复）

- **文件**：`src/modules/textbooks/actions.ts`
- **行号**：46-50
- **问题**：仍在本地定义 `ActionState` 类型，而非从 `@/shared/types/action-state` 导入
- **修复建议**：删除本地定义，改为 `import type { ActionState } from "@/shared/types/action-state"`

#### P1-7：elective/data-access.ts 跨模块直查（v2 新发现）

- **文件**：`src/modules/elective/data-access.ts`
- **行号**：77-106（`buildCourseSelect`）、231-242（`getSubjectOptions`）
- **问题**：`buildCourseSelect` 直接 `leftJoin(users/subjects/grades)`；本地 `getSubjectOptions` 直查 `subjects` 表且与 school 模块重复
- **修复建议**：移除 join，改为先查主表再用 `getUserNamesByIds`/`getSubjectOptions`/`getGradeOptions` 批量解析；删除本地 `getSubjectOptions` 改用 school 模块

#### P1-8：elective selectCourse/dropCourse 缺事务（v2 新发现）

- **文件**：`src/modules/elective/data-access-operations.ts`
- **行号**：97-172（selectCourse）、174-241（dropCourse）
- **问题**：FCFS 模式下 update + insert 两步无事务包裹；dropCourse 最多 5 个连续写操作无事务
- **修复建议**：用 `db.transaction` 包裹所有写操作

#### P1-9：classes/actions.ts as 断言（v2 新发现）

- **文件**：`src/modules/classes/actions.ts`
- **行号**：47, 521, 565
- **问题**：`v as ClassSubject`、`weekday as 1|2|3|4|5|6|7` 使用 as 断言
- **修复建议**：在 schema.ts 中使用 Zod transform 使解析后直接产出目标类型

#### P1-10：school/actions.ts 使用 .parse() 而非 .safeParse()（v2 新发现）

- **文件**：`src/modules/school/actions.ts`
- **行号**：33, 60, 98, 129, 171, 202, 256, 289
- **问题**：所有 action 使用 `Schema.parse()` 而非 `safeParse()`，验证失败抛 ZodError，无法返回结构化 fieldErrors
- **修复建议**：改用 `safeParse()`，失败时返回 `{ success: false, errors: parsed.error.flatten().fieldErrors }`

#### P1-11：多个模块函数缺返回类型标注（v2 新发现 + v1 部分未修复）

| 模块 | 文件 | 函数 |
|------|------|------|
| classes | data-access.ts:53,60,93,95,100,107 | isDuplicateInvitationCodeError, generateInvitationCode, normalizeSortText, parseFirstInt, compareGradeLabel, compareClassLike |
| school | data-access.ts:24 | toIso |
| attendance | data-access.ts:70 | resolveRecorderNames |
| exams | ai-pipeline.ts:68,177,309,453,480,499,571,712 | sanitizeJsonCandidate, normalizeScores, buildAiMessages, splitStructureItems, mapWithConcurrency, parseQuestionDetail, buildQuestionContent, previewToDraft |
| exams | data-access.ts:269 | buildOrderedQuestionsFromStructure |
| grades | data-access.ts:57, data-access-analytics.ts:34 | buildScopeClassFilter |
| textbooks | data-access.ts:19,25 | normalizeOptional, sortChapters |

#### P1-12：files/data-access.ts conditions 隐式 any[]（v1 未修复）

- **文件**：`src/modules/files/data-access.ts`
- **行号**：201
- **问题**：`const conditions = []` 无类型注解，推断为 `any[]`
- **修复建议**：改为 `const conditions: SQL[] = []`

#### P1-13：course-plans updateCoursePlanItemAction 缺 revalidatePath（v1 部分修复）

- **文件**：`src/modules/course-plans/actions.ts`
- **行号**：197-234
- **问题**：v1 指出的 deleteCoursePlanItemAction 和 toggleCoursePlanItemCompletedAction 已修复，但 `updateCoursePlanItemAction` 仍缺 `revalidatePath`
- **修复建议**：在 `await updateCoursePlanItem(id, parsed.data)` 后添加 `revalidatePlanPaths()` 调用

### 3.3 P2 级别（迭代优化）

#### 性能类

| 模块 | 文件 | 问题 |
|------|------|------|
| grades | data-access.ts:273,377,397 | 3 个查询函数未用 React.cache() |
| elective | data-access.ts:231 | getSubjectOptions 未用 cache() |
| course-plans | data-access.ts:302-307 | reorderCoursePlanItems 循环内串行 await |
| diagnostic | data-access.ts:119-140 | updateMasteryFromSubmission 循环内串行 await |
| proctoring | data-access.ts:271-287 | getStudentProctoringStatuses 串行查询未并行化 |
| diagnostic | data-access.ts:147-159 | getClassMasterySummary 串行查询未并行化 |
| grades | export.ts:129 | 循环内 find O(n) 查找，应改用 Map |
| school | data-access.ts:406-469 | isGradeHead/isGradeManager/findGradeIdByHeadAndName 未用 cache() |

#### 代码质量类

| 模块 | 文件 | 问题 |
|------|------|------|
| school | data-access.ts:26-206 | 8 个函数 try-catch 吞错误返回空数组 |
| files | data-access.ts | 10 处静默 catch 吞错误 |
| classes | data-access.ts:371-373, data-access-admin.ts:88-89,244-247, data-access-students.ts:159-160 | 多处 try-catch 吞错误 |
| course-plans | data-access.ts:143-162,166-189,312-323 | 3 处 try-catch 吞错误 |
| announcements | data-access.ts:88-91,119-122 | catch 已加 console.error 但仍吞错误 |
| announcements | actions.ts:26-230 | 6 处重复 try/catch 块未抽取公共 helper |
| diagnostic | data-access-reports.ts:22,207-208 | void round2 死代码 |
| scheduling | data-access.ts:113-114 | select 中 requesterName 字段冗余 |
| elective | data-access.ts:46-75, data-access-selections.ts:46-74 | mapCourseRow 重复定义 |

#### TS 规范类

| 模块 | 文件 | 问题 |
|------|------|------|
| users | import-export.ts:14 | as 断言未加注释 |
| users | import-export.ts:98 | conditions 隐式 any[] |
| messaging | data-access.ts:84 | conds 隐式 any[] |
| audit | data-access.ts:40,96,161 | conditions 隐式 any[] |
| classes | data-access.ts:675 | 非空断言 `!` |
| textbooks | data-access.ts:314 | 非空断言 `stack.pop()!` |
| notifications | external-sdk.d.ts | 多处 any（有 eslint-disable 注释） |
| notifications | wechat-channel.ts:106 | as 断言未加注释 |

#### 命名规范类

| 模块 | 文件 | 问题 |
|------|------|------|
| questions | actions.ts:26 | createNestedQuestion 命名不一致 |
| settings | actions.ts:60-63 | getAiProviderSummaries 返回非 ActionState |

#### 架构/类型位置类

| 模块 | 文件 | 问题 |
|------|------|------|
| layout | navigation.ts:30-31 | permission 字段为 string 而非 Permission 类型 |
| layout | navigation.ts:34 | Role 类型应迁移至 shared/types |
| audit | actions.ts:63-205 | Excel 导出逻辑内联在 actions 层 |

#### 文件行数类

| 模块 | 文件 | 行数 | 建议 |
|------|------|------|------|
| exams | ai-pipeline.ts | 916 行 | 拆分为 prompts/json-parser/schemas/index |
| classes | data-access.ts | 866 行 | 拆分 enrollment 相关函数到 data-access-enrollment.ts |

#### 数据一致性/业务逻辑类

| 模块 | 文件 | 问题 |
|------|------|------|
| elective | data-access-operations.ts:139-148 | FCFS 并发超卖风险（架构图 P2-15） |
| elective | data-access-operations.ts:49 | runLottery 使用 Math.random 不可复现（架构图 P2-14） |
| diagnostic | data-access-reports.ts:113 | 班级报告 studentId 字段复用（架构图 P2-16） |

---

## 四、按模块详细核查

### 4.1 exams 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: persistAiGeneratedExamDraft 直写 questions 表 | ✅ 已修复 | 改用 createQuestionWithRelations |
| P0: getExams 等直查 classes 表 | ✅ 已修复 | 改用 getClassGradeIdsByClassIds |
| P1: 直接查询 subjects/grades 表 | ❌ 未修复 | 仍直查 school 模块表 |
| P1: actions.ts as 断言 | ✅ 已修复 | 改用 as unknown + safeParse |
| P2: import { ActionState } 未用 import type | ✅ 已修复 | 已改为 import type |
| P2: ai-pipeline.ts 912 行超长 | ❌ 未修复 | 当前 916 行 |
| P2: data-access.ts as string[] 断言 | ✅ 已修复 | 改用 getStringArray 类型守卫 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | ai-pipeline.ts:68,177,309,453,480,499,571,712 | 8 个函数缺少显式返回类型标注 |
| P2 | data-access.ts:269 | buildOrderedQuestionsFromStructure 缺返回类型 |

### 4.2 homework 模块

#### v1 修复情况（100% 修复）

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: data-access.ts 直查 exams/classEnrollments/subjects/users 表 | ✅ 已修复 | 改用跨模块 data-access 接口 |
| P1: data-access-write.ts 直查 classes/classEnrollments/classSubjectTeachers/exams 表 | ✅ 已修复 | 改用跨模块接口 |
| P1: stats-service.ts 直查 classEnrollments/classes/exams/users 表 | ✅ 已修复 | 改用跨模块接口 |
| P1: data-access.ts:39 as 断言 | ✅ 已修复 | 改用 isHomeworkQuestionContent 类型守卫 |
| P2: data-access-write.ts 循环内串行 await 未用事务 | ✅ 已修复 | 已用 db.transaction 包裹 |
| P2: data-access.ts 使用 auth() 而非 getAuthContext() | ✅ 已修复 | 不再使用 auth() |

**v2 无新发现问题，模块状态良好。**

### 4.3 questions 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: schema.ts z.any() | ✅ 已修复 | 改为 z.unknown() |
| P0: actions.ts 未返回 ActionState | ✅ 已修复 | 包装为 ActionState<T> |
| P1: data-access.ts 直查 textbooks 模块表 | ❌ 未修复 | 仍直查 knowledgePoints/chapters/textbooks |
| P1: actions.ts import type | ✅ 已修复 | 已改为 import type |
| P2: createNestedQuestion 命名不一致 | ❌ 未修复 | 仍为 createNestedQuestion |

**v2 无新发现问题。**

### 4.4 grades 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: N+1 查询 | ✅ 已修复 | 改为 inArray 批量查询 + Map 分组 |
| P1: 跨模块直查 | ✅ 已修复 | 改用跨模块 data-access 接口 |
| P1: 动态 import | ✅ 已修复 | 改为静态 import |
| P1: 除零 bug | ✅ 已修复 | 添加 `if (fullScores[i] <= 0) continue` |
| P2: 未用 React.cache() | ⚠️ 部分修复 | 4 个函数已用 cache()，3 个仍未用 |
| P2: includes O(n) 查找 | ✅ 已修复 | 改用 Set.has() |
| P2: 重复 filter | ✅ 已修复 | 改用单次 reduce |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:57, data-access-analytics.ts:34 | buildScopeClassFilter 缺返回类型 |
| P2 | export.ts:129 | 循环内 find O(n) 查找，应改用 Map |

### 4.5 textbooks 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: 无 Zod 验证 | ❌ 未修复 | 仍无 schema.ts，所有 Action 手动校验 |
| P0: 14 处 as 断言 | ✅ 已修复 | 已清理所有 as 断言 |
| P1: 本地定义 ActionState | ❌ 未修复 | 仍在本地定义 |
| P1: import type | ✅ 已修复 | 已改为 import type |
| P1: data-access.ts as 断言 | ✅ 已修复 | 改用 isChapterNode 类型守卫 |
| P2: 非空断言 | ⚠️ 部分修复 | 原位置已修复，但 314 行仍有 stack.pop()! |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:19,25 | normalizeOptional、sortChapters 缺返回类型 |

### 4.6 classes 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: actions.ts 直接 DB 操作 | ✅ 已修复 | 已下沉到 data-access |
| P0: getTeacherClasses 混入 homework/scheduling | ⚠️ 部分修复 | 架构合规，但职责仍混合 |
| P0: data-access-stats.ts 直查 homework/exams | ✅ 已修复 | 改用 homework/data-access-classes |
| P0: data-access-students.ts 直查 homework/exams | ✅ 已修复 | 同上 |
| P1: 无 schema.ts | ✅ 已修复 | 已创建 schema.ts |
| P1: as 断言 | ✅ 已修复 | 原位置已清理 |
| P1: 箭头函数缺返回类型 | ⚠️ 部分修复 | 6 个同步箭头函数仍缺 |
| P1: data-access-schedule.ts 直查 classSchedule | ❌ 未修复 | 仍直查 scheduling 模块表 |
| P2: 不可达代码 | ✅ 已修复 | 已删除 |
| P2: 串行查询未并行化 | ✅ 已修复 | 已用 Promise.all |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P1 | actions.ts:47,521,565 | as 断言（v as ClassSubject、weekday as 1\|2\|...\|7） |
| P2 | data-access.ts:675 | 非空断言 `!` |
| P2 | data-access.ts:371-373 等 | 多处 try-catch 吞错误 |
| P2 | data-access.ts | 文件 866 行超 800 行建议上限 |

### 4.7 school 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: actions 层直接 DB 操作 | ✅ 已修复 | DB 操作下沉到 data-access |
| P2: try-catch 吞错误 | ❌ 未修复 | 8 个函数仍吞错误 |
| P2: logAudit 阻塞响应 | ✅ 已修复 | 已用 after() 异步执行 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P1 | actions.ts:33,60,98,129,171,202,256,289 | 使用 .parse() 而非 .safeParse() |
| P1 | data-access.ts:24 | toIso 缺返回类型 |
| P2 | data-access.ts:406-469 | 3 个跨模块查询函数未用 cache() |

### 4.8 scheduling 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: actions.ts 直查 users 表 | ✅ 已修复 | 改用 getUserNamesByIds |
| P0: 4 个函数缺返回类型 | ✅ 已修复 | 已添加返回类型 |
| P1: 非空断言（3 处） | ✅ 已修复 | 改用显式判空 |
| P2: auto-scheduler.ts 310 行 | ⚠️ 部分修复 | 311 行，多个函数超 40 行 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:113-114 | select 中 requesterName 字段冗余 |
| P2 | data-access.ts:135-145 | 用户查询应使用 inArray 替代 or(...map(eq)) |

### 4.9 attendance 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: Record<string, unknown> 丢失类型安全 | ✅ 已修复 | 改用 Partial<typeof attendanceRecords.$inferSelect> |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P1 | data-access.ts:70 | resolveRecorderNames 缺返回类型 |

### 4.10 course-plans 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: 缺 revalidatePath | ⚠️ 部分修复 | delete/toggle 已修复，update 仍缺 |
| P1: as 断言 | ✅ 已修复 | 已清理 |
| P2: 循环内串行 await | ❌ 未修复 | 仍串行 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:143-162,166-189,312-323 | 3 处 try-catch 吞错误 |

### 4.11 users 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: updateUserProfile 绕过权限 | ✅ 已修复 | 改用 requirePermission + Zod + ActionState |
| P0: 硬编码弱密码 | ✅ 已修复 | 改用 randomBytes 生成 |
| P1: actions 层直接 DB 操作 | ✅ 已修复 | 下沉到 data-access |
| P1: batchImportUsers 无事务 | ✅ 已修复 | 每个用户创建包裹在 db.transaction |
| P2: rolePriority 命名 | ✅ 已修复 | 已移除，改用 resolvePrimaryRole |
| P2: normalizeRoleName 重复 | ✅ 已修复 | 改用 shared |
| P2: conditions 隐式 any[] | ❌ 未修复 | 仍为 `const conditions = []` |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | import-export.ts:14 | as 断言未加注释 |

### 4.12 messaging 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: 循环依赖 | ✅ 已修复 | 表所有权移交 notifications |
| P1: 5 个 Action 用 requireAuth | ✅ 已修复 | 改用 requirePermission |
| P1: getRecipients 直查跨模块表 | ❌ 未修复 | 仍 JOIN classEnrollments/classes |
| P1: 无 Zod 验证 | ✅ 已修复 | 已用 UpdateNotificationPreferencesSchema |
| P2: 非空断言 | ✅ 已修复 | 改用 ?? null |
| P2: 缺返回类型 | ✅ 已修复 | 已添加 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:84 | conds 隐式 any[] |

### 4.13 notifications 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: 反向依赖 messaging | ✅ 已修复 | 表所有权归 notifications |
| P0: in-app-channel 动态 import messaging | ✅ 已修复 | 改为静态 import |
| P0: 非法 as 断言 | ✅ 已修复 | 新增 mapPayloadTypeToNotificationType |
| P1: actions.ts 直查 classes 表 | ✅ 已修复 | 改用 classes data-access 函数 |
| P1: 参数无 Zod 验证 | ❌ 未修复 | 仍用手动 if 检查 |
| P2: 缺返回类型 | ✅ 已修复 | 已添加 |
| P2: external-sdk.d.ts any | ❌ 未修复 | 有 eslint-disable 注释 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | wechat-channel.ts:106 | as 断言未加注释 |

### 4.14 parent 模块

#### v1 修复情况（100% 修复）

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: getChildBasicInfo 直查跨模块表 | ✅ 已修复 | 改用各模块 data-access 函数 |
| P2: as 断言 | ✅ 已修复 | 改用 isWeekday 类型守卫 |
| P2: 串行查询 | ✅ 已修复 | 改用 Promise.all |

**v2 无新发现问题，模块状态良好，是跨模块通信的标杆实现。**

### 4.15 audit 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: 导出函数数据截断 | ✅ 已修复 | 改用分页循环拉取全部数据 |
| P2: as 断言 | ✅ 已修复 | 已清理 |
| P2: Excel 导出逻辑内联 | ❌ 未修复 | 仍内联在 actions |
| P2: conditions 隐式 any[] | ❌ 未修复 | 3 处仍为 `const conditions = []` |

### 4.16 elective 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: data-access-selections.ts 直查 classes 表 | ✅ 已修复 | 改用跨模块接口 |
| P1: runLottery 无事务 | ✅ 已修复 | 已用 db.transaction |
| P1: 循环内逐条 await | ✅ 已修复 | 改用 inArray 批量更新 |
| P1: as 断言 | ✅ 已修复 | 已清理 |
| P2: 串行查询未并行化 | ✅ 已修复 | 改用 Promise.all |
| P2: 未用 React.cache() | ⚠️ 部分修复 | 大部分已用，getSubjectOptions 仍未用 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P1 | data-access.ts:77-106 | buildCourseSelect 跨模块 join users/subjects/grades |
| P1 | data-access.ts:231-242 | 本地 getSubjectOptions 直查 subjects 表且与 school 重复 |
| P1 | data-access-operations.ts:97-172 | selectCourse 缺事务包裹 |
| P1 | data-access-operations.ts:174-241 | dropCourse 缺事务包裹 |
| P2 | data-access-operations.ts:139-148 | FCFS 并发超卖风险 |
| P2 | data-access-operations.ts:49 | runLottery 使用 Math.random 不可复现 |
| P2 | data-access.ts:46-75, data-access-selections.ts:46-74 | mapCourseRow 重复定义 |

### 4.17 proctoring 模块

#### v1 修复情况（100% 修复）

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P0: actions.ts 直接 DB 操作 | ✅ 已修复 | 下沉到 data-access |
| P1: import type | ✅ 已修复 | 已改为 import type |
| P1: as 断言 | ✅ 已修复 | 改用类型守卫 |
| P1: requireAuth | ✅ 已修复 | 改用 requirePermission |
| P1: 直查 exams/examSubmissions 表 | ✅ 已修复 | 改用跨模块函数 |
| P1: 多处 as 断言 | ✅ 已修复 | 改用 toExamMode/isSubmissionStatus |
| P2: 未调用 revalidatePath | ✅ 已修复 | 已添加 |
| P2: 串行查询 | ✅ 已修复 | 改用 Promise.all |
| P2: 重复 filter | ✅ 已修复 | 改用单次循环 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:271-287 | getStudentProctoringStatuses 串行查询未并行化 |

### 4.18 diagnostic 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: 4 个 Action 无 Zod | ✅ 已修复 | 新增 schema.ts，6 个 Action 全用 Zod |
| P1: 直查跨模块表 | ✅ 已修复 | 改用跨模块 data-access |
| P1: as 断言 | ✅ 已修复 | 改用 isStringArray 类型守卫 |
| P2: 循环内 find | ✅ 已修复 | 改用 Map |
| P2: 循环内串行 await | ❌ 未修复 | updateMasteryFromSubmission 仍串行 |
| P2: 重复 filter | ✅ 已修复 | 改用单次循环 |
| P2: 动态 import | ✅ 已修复 | 改为静态 import |
| P2: void round2 死代码 | ❌ 未修复 | 仍存在 |
| P2: 未用 React.cache() | ✅ 已修复 | 全部用 cache() 包装 |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | data-access.ts:147-159 | getClassMasterySummary 串行查询未并行化 |

### 4.19 dashboard 模块

**v1 无违规问题，v2 仍为标杆模块。** 正确使用 Promise.all 并行获取多模块数据，正确使用 cache()，正确通过各模块 data-access 通信。

### 4.20 files 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: conditions 隐式 any[] | ❌ 未修复 | 仍为 `const conditions = []` |
| P1: or(...)! 非空断言 | ✅ 已修复 | 改用显式判断 |
| P2: 循环内串行 await | ⚠️ 部分修复 | 主路径已批量删除，catch 回退仍串行 |
| P2: 9 处静默 catch | ❌ 未修复 | 实际 10 处 |
| P2: 未用 React.cache() | ✅ 已修复 | 全部用 cache() 包装 |

### 4.21 announcements 模块

#### v1 修复情况

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: as string 断言 | ✅ 已修复 | 新增 toIso/toIsoRequired 工具函数 |
| P2: 冗余 as 断言 | ✅ 已修复 | 已清理 |
| P2: catch 吞错误 | ⚠️ 部分修复 | 已加 console.error 但仍吞错误 |
| P2: 类型重复定义 | ✅ 已修复 | 已修复 |
| P2: requireAuth | ✅ 已修复 | 改用 requirePermission |
| P2: 重复 try/catch | ❌ 未修复 | 6 处仍重复 |

### 4.22 settings 模块

#### v1 修复情况（100% 修复）

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P1: 无 data-access.ts | ✅ 已修复 | 新建 data-access.ts |
| P1: actions-password.ts 无 data-access | ✅ 已修复 | DB 操作下沉 |
| P1: 无 Zod 验证 | ✅ 已修复 | 新增 ChangePasswordSchema |
| P2: 类型定义位置 | ✅ 已修复 | 新建 types.ts |
| P2: 缺返回类型 | ✅ 已修复 | 已添加 |
| P2: 串行查询 | ✅ 已修复 | 改用 Promise.all |
| P2: 布尔命名 | ✅ 已修复 | 改为 hasDefault/isNextDefault/shouldMakeDefault |
| P2: requireAuth | ✅ 已修复 | 改用 requirePermission |
| P2: 串行查询 | ✅ 已修复 | 改用 Promise.all |

#### v2 新发现问题

| 严重程度 | 文件 | 问题 |
|---------|------|------|
| P2 | actions.ts:60-63 | getAiProviderSummaries 返回非 ActionState |

### 4.23 layout 模块

#### v1 修复情况（0% 修复）

| v1 问题 | 修复状态 | 说明 |
|---------|---------|------|
| P2: permission 字段为 string | ❌ 未修复 | 仍为 string |
| P2: Role 类型位置 | ❌ 未修复 | 仍在 navigation.ts |

---

## 五、v2 新发现问题清单

### 5.1 P1 级别新问题（16 个）

| 编号 | 模块 | 文件 | 问题 |
|------|------|------|------|
| N1 | elective | data-access.ts:77-106 | buildCourseSelect 跨模块 join users/subjects/grades |
| N2 | elective | data-access.ts:231-242 | 本地 getSubjectOptions 直查 subjects 表且与 school 重复 |
| N3 | elective | data-access-operations.ts:97-172 | selectCourse 缺事务包裹 |
| N4 | elective | data-access-operations.ts:174-241 | dropCourse 缺事务包裹 |
| N5 | classes | actions.ts:47,521,565 | as 断言（v as ClassSubject、weekday as 1\|2\|...\|7） |
| N6 | school | actions.ts:33 等 | 使用 .parse() 而非 .safeParse() |
| N7 | school | data-access.ts:24 | toIso 缺返回类型 |
| N8 | attendance | data-access.ts:70 | resolveRecorderNames 缺返回类型 |
| N9 | exams | ai-pipeline.ts | 8 个函数缺返回类型 |
| N10 | exams | data-access.ts:269 | buildOrderedQuestionsFromStructure 缺返回类型 |
| N11 | grades | data-access.ts:57, data-access-analytics.ts:34 | buildScopeClassFilter 缺返回类型 |
| N12 | textbooks | data-access.ts:19,25 | normalizeOptional、sortChapters 缺返回类型 |
| N13 | settings | actions.ts:60-63 | getAiProviderSummaries 返回非 ActionState |
| N14 | messaging | data-access.ts:84 | conds 隐式 any[] |
| N15 | users | import-export.ts:14 | as 断言未加注释 |
| N16 | notifications | wechat-channel.ts:106 | as 断言未加注释 |

### 5.2 P2 级别新问题（25 个）

| 编号 | 模块 | 文件 | 问题 |
|------|------|------|------|
| N17 | classes | data-access.ts:675 | 非空断言 `!` |
| N18 | classes | data-access.ts:371-373 等 | 多处 try-catch 吞错误 |
| N19 | classes | data-access.ts | 文件 866 行超 800 行建议上限 |
| N20 | school | data-access.ts:406-469 | 3 个跨模块查询函数未用 cache() |
| N21 | scheduling | data-access.ts:113-114 | select 中 requesterName 字段冗余 |
| N22 | scheduling | data-access.ts:135-145 | 用户查询应使用 inArray |
| N23 | course-plans | data-access.ts:143-162 等 | 3 处 try-catch 吞错误 |
| N24 | grades | export.ts:129 | 循环内 find O(n) 查找 |
| N25 | proctoring | data-access.ts:271-287 | getStudentProctoringStatuses 串行查询 |
| N26 | diagnostic | data-access.ts:147-159 | getClassMasterySummary 串行查询 |
| N27 | elective | data-access-operations.ts:139-148 | FCFS 并发超卖风险 |
| N28 | elective | data-access-operations.ts:49 | runLottery 使用 Math.random |
| N29 | elective | data-access.ts:46-75 等 | mapCourseRow 重复定义 |
| N30 | users | import-export.ts:98 | conditions 隐式 any[] |
| N31 | audit | data-access.ts:40,96,161 | conditions 隐式 any[] |

---

## 六、架构文档同步提醒

根据项目规则"改码必同步图"，以下架构图信息需更新：

### 6.1 需更新的架构文档

| 文档 | 需更新内容 |
|------|-----------|
| `docs/architecture/004_architecture_impact_map.md` | 1. exams/actions.ts 行数（v1 记录 691，实际 771）<br>2. exams/ai-pipeline.ts 行数（v1 记录 857，实际 916）<br>3. settings 导出函数列表（v1 记录 getAiProvidersAction 等，实际为 getAiProviderSummaries/upsertAiProviderAction/testAiProviderAction）<br>4. P2-11 死代码 void wasPublished 状态（已修复）<br>5. announcements 依赖 school 模块（仅 components，非后端）<br>6. elective 依赖关系需补充 classes/school/users<br>7. messaging↔notifications 循环依赖已解决<br>8. classes 跨模块直查 homework/exams 已解决 |

### 6.2 需同步的代码变更

本轮修复涉及大量模块结构调整，必须同步更新 004 和 005 架构文档：

- **新增模块文件**：classes/schema.ts、settings/data-access.ts、settings/types.ts、diagnostic/schema.ts
- **新增跨模块接口**：classes 暴露 getClassGradeIdsByClassIds、getStudentIdsByClassId 等；exams 暴露 getExamIdsByGradeIds、getExamWithQuestionsForHomework 等；users 暴露 getUserNamesByIds、getUserBasicInfo 等；school 暴露 getSubjectOptions、getGradeOptions 等
- **表所有权迁移**：messageNotifications、notificationPreferences 表所有权从 messaging 移交至 notifications
- **权限点新增**：USER_PROFILE_UPDATE、PASSWORD_SELF_CHANGE 等

---

## 七、总体评价与建议

### 7.1 修复成效

本次 v2 核查显示，项目在 v1 报告后进行了大规模且有成效的修复：

1. **所有 P0 问题已全部修复**（14/14）：包括跨模块直写 DB、循环依赖、硬编码弱密码、N+1 查询等高危问题
2. **P1 问题修复率 65%**：剩余 14 个未修复 + 7 个部分修复
3. **4 个模块达到 100% 修复率**：homework、parent、proctoring、settings
4. **架构层面显著改善**：
   - messaging↔notifications 循环依赖彻底消除
   - 跨模块直查 DB 大幅减少（exams、homework、grades、classes、proctoring、diagnostic 等模块已改用 data-access 接口）
   - parent 模块成为跨模块通信的标杆实现

### 7.2 仍需改进的领域

1. **textbooks 模块**：P0 问题（无 Zod 验证）仍未修复，是所有模块中唯一未实现输入验证的 Server Action 文件
2. **跨模块直查残留**：exams→school、questions→textbooks、classes→scheduling、messaging→classes 仍存在直查
3. **函数返回类型标注**：多个模块仍存在箭头函数缺返回类型的问题（classes、school、attendance、exams、grades、textbooks）
4. **隐式 any[]**：`const conditions = []` 在 users、messaging、audit、files 等模块普遍存在
5. **错误处理**：try-catch 吞错误在 school、files、classes、course-plans 等模块仍普遍存在
6. **elective 模块**：v2 新发现 selectCourse/dropCourse 缺事务、data-access.ts 跨模块直查等问题

### 7.3 下一阶段优先修复建议

**第一优先级（P0/P1 核心问题）**：
1. textbooks 模块新建 schema.ts，所有 Action 改用 Zod safeParse
2. textbooks/actions.ts 改用共享 ActionState 类型
3. exams、questions、classes、messaging 模块消除剩余跨模块直查
4. elective selectCourse/dropCourse 加事务包裹
5. school/actions.ts 改用 safeParse
6. 补齐所有函数返回类型标注

**第二优先级（P2 系统性优化）**：
1. 全项目统一修复 `const conditions = []` 隐式 any[]（改为 `SQL[]`）
2. 清理 try-catch 吞错误（至少加 console.error 或向上抛出）
3. 补齐 React.cache() 包装
4. 串行查询改用 Promise.all
5. 同步架构文档

**第三优先级（代码质量）**：
1. 抽取重复代码（mapCourseRow、handleActionError、buildExcelSheet 等）
2. 清理死代码（void round2 等）
3. 拆分超长文件（ai-pipeline.ts、classes/data-access.ts）
4. layout 模块类型规范修复