NextEdu/bugs/back_bug.md

后端模块规范核查报告

核查日期：2026-06-18 核查范围：src/modules/ 下所有后端 .ts 文件（actions / data-access / schema / types / services 等非 components、非 hooks 文件） 核查依据：

• .trae/rules/project_rules.md 项目规则
• docs/standards/coding-standards.md 编码规范
• docs/architecture/004_architecture_impact_map.md 架构影响地图
• Vercel React Best Practices 性能优化规则（react-best-practices 技能）

严重程度定义：

• P0：严重违规，破坏架构分层 / 安全漏洞 / 数据正确性问题，必须立即修复
• P1：明确违规，影响可维护性 / 类型安全 / 性能，应尽快修复
• P2：轻微违规或代码异味，可在迭代中优化

---

目录

• 一、汇总统计
• 二、P0 严重问题清单（立即修复）
• 三、按模块详细核查
  • 3.1 exams（考试模块）
  • 3.2 homework（作业模块）
  • 3.3 questions（题库模块）
  • 3.4 grades（成绩模块）
  • 3.5 textbooks（教材模块）
  • 3.6 classes（班级模块）
  • 3.7 school（学校模块）
  • 3.8 scheduling（排课模块）
  • 3.9 attendance（考勤模块）
  • 3.10 course-plans（教学计划模块）
  • 3.11 users（用户模块）
  • 3.12 messaging（消息模块）
  • 3.13 notifications（通知模块）
  • 3.14 parent（家长模块）
  • 3.15 audit（审计模块）
  • 3.16 elective（选修课模块）
  • 3.17 proctoring（监考模块）
  • 3.18 diagnostic（诊断模块）
  • 3.19 dashboard（仪表盘模块）
  • 3.20 files（文件模块）
  • 3.21 announcements（公告模块）
  • 3.22 settings（设置模块）
  • 3.23 layout（布局模块）
• 四、跨模块共性问题
• 五、性能优化专项（react-best-practices）
• 六、优先修复路线图

---

一、汇总统计

1.1 按严重程度

严重程度	数量	典型问题
P0	14	跨模块直查/直写 DB 表、循环依赖、z.any()、N+1 查询、未返回 ActionState、无 Zod 验证、硬编码弱密码
P1	60+	as 断言滥用、requireAuth 替代 requirePermission、缺少 import type、动态 import、无事务、除零 bug、导出数据截断
P2	100+	非空断言 !、未用 React.cache()、串行查询未并行化、重复 filter、静默吞异常、缺返回类型标注、文档不同步

1.2 按问题类别

问题类别	涉及文件数	关键发现
架构违规	25+	跨模块直查 DB 是最普遍问题；messaging↔notifications 循环依赖；actions 层直接 DB 操作
TS 规范	30+	as 断言大量存在；z.any()；import type 未用；非空断言 !；隐式 any[]
Server Action 规范	12+	requireAuth 替代 requirePermission；未返回 ActionState；无 Zod 验证；缺 revalidatePath
性能	20+	N+1 查询；动态 import；未用 cache()；串行 await 循环；重复 filter 遍历
安全	2	硬编码弱密码 "123456"；as 断言掩盖类型不兼容
行数	1	exams/ai-pipeline.ts 912 行（超 800 建议，未超 1000 硬上限）

1.3 模块问题分布

模块	P0	P1	P2	总体评价
exams	3	5	6	跨模块直查/直写严重
homework	0	8	5	跨模块直查普遍
questions	2	2	3	z.any() + 未返回 ActionState
grades	1	6	7	N+1 查询 + 跨模块直查
textbooks	2	2	4	无 Zod 验证 + as 断言
classes	3	8	6	耦合最严重，混入多模块逻辑
school	1	1	2	actions 层直接 DB 操作
scheduling	0	4	3	缺返回类型标注
attendance	0	1	0	整体规范
course-plans	0	3	2	缺 revalidatePath
users	1	3	4	硬编码弱密码 + 无事务
messaging	1	6	6	循环依赖 + requireAuth
notifications	3	3	8	循环依赖 + as 断言类型不兼容
parent	0	2	2	跨模块直查
audit	0	4	6	导出数据截断
elective	0	3	5	无事务 + 串行更新
proctoring	1	6	3	actions 层直接 DB 操作
diagnostic	0	2	5	跨模块直查 + 性能问题
dashboard	0	0	0	标杆模块
files	0	2	3	隐式 any[] + 非空断言
announcements	0	1	5	as 断言 + 错误吞没
settings	0	3	9	缺 data-access 层 + 无 Zod
layout	0	0	2	类型松散

---

二、P0 严重问题清单（立即修复）

P0-1：exams 模块直写 questions 表

• 文件：src/modules/exams/data-access.ts
• 行号：2, 318
• 问题：persistAiGeneratedExamDraft 直接 db.insert(questions) 写入 questions 表（属 questions 模块），破坏模块封装
• 修复：改为调用 questions/data-access.createQuestionWithRelations() 或在 questions 模块暴露批量插入接口

P0-2：exams 模块直查 classes 表

• 文件：src/modules/exams/data-access.ts
• 行号：2, 72-80, 156-163, 357-364
• 问题：getExams/getExamById/getExamsDashboardStats 直接查询 classes 表获取 gradeId
• 修复：在 classes 模块暴露 getGradeIdsByClassIds(classIds) 接口

P0-3：questions/schema.ts 使用 z.any()

• 文件：src/modules/questions/schema.ts
• 行号：6
• 问题：content: z.any() 违反"禁止 any"规则
• 修复：改为 z.unknown()

P0-4：questions/actions.ts 未返回 ActionState

• 文件：src/modules/questions/actions.ts
• 行号：154, 166-175
• 问题：getQuestionsAction 和 getKnowledgePointOptionsAction 直接返回原始结果，未包装为 ActionState<T>，错误时 throw 而非返回失败状态
• 修复：改为 Promise<ActionState<...>> 返回 { success: true, data: result }

P0-5：textbooks 模块无 Zod 验证 + 大量 as 断言

• 文件：src/modules/textbooks/actions.ts
• 行号：全文件，特别 54-58, 92-98, 154, 219-221, 259-261
• 问题：缺少 schema.ts 文件，所有 Action 均无 Zod 验证，使用手动 if (!rawData.title) 检查；14 处 formData.get("title") as string 断言
• 修复：新建 schema.ts，为每个 Action 定义 Zod schema；改用 typeof 守卫或 getStringValue() 辅助函数

P0-6：grades 模块 N+1 查询

• 文件：src/modules/grades/data-access-analytics.ts
• 行号：142-185
• 问题：getClassComparison 中 for (const cls of classRows) { ... await db.select(...) } 循环内串行查询，N+1 问题
• 修复：用 inArray 一次性查询所有班级的成绩，再在内存分组

P0-7：classes 模块跨模块直接查询 DB 表

• 文件：src/modules/classes/data-access-stats.ts、src/modules/classes/data-access-students.ts
• 行号：data-access-stats.ts: 11-18；data-access-students.ts: 10-14
• 问题：直接导入并查询 homeworkAssignments、homeworkSubmissions、homeworkAssignmentTargets、homeworkAssignmentQuestions、exams 等其他模块的表
• 修复：通过 homework 模块的 data-access 暴露的函数获取数据

P0-8：school 模块 actions 层直接操作 DB

• 文件：src/modules/school/actions.ts
• 行号：7-8, 26-30, 53-59, 73, 96-108, 133-147, 161, 182-186, 211-217, 233, 261-268, 294-303, 317
• 问题：actions 层直接导入 db 和所有 schema，所有 mutation 直接操作 DB，未下沉到 data-access 层
• 修复：在 data-access.ts 中新增 createDepartment、updateDepartment、deleteDepartment、createSchool 等函数

P0-9：proctoring 模块 actions 层直接查询 DB

• 文件：src/modules/proctoring/actions.ts
• 行号：11-13, 79-84
• 问题：actions.ts（编排层）直接导入 db、examSubmissions 并执行 DB 查询，违反三层架构
• 修复：将 submission 归属校验逻辑移至 data-access.ts

P0-10：messaging↔notifications 循环依赖

• 文件：src/modules/messaging/data-access.ts、src/modules/notifications/data-access.ts、src/modules/notifications/channels/in-app-channel.ts
• 行号：messaging/data-access.ts: 192-203；notifications/data-access.ts: 20-21；in-app-channel.ts: 50
• 问题：messaging 写 messageNotifications 表，notifications 反向依赖 messaging，形成循环依赖
• 修复：将 messageNotifications 和 notificationPreferences 表所有权移交 notifications 模块

P0-11：notifications/in-app-channel.ts 非法 as 断言

• 文件：src/modules/notifications/channels/in-app-channel.ts
• 行号：54
• 问题：payload.type as "message" | "announcement" | "homework" | "grade" 源类型 "info"|"warning"|"error"|"success" 与目标类型不兼容，as 断言非法
• 修复：重新设计类型映射函数，或统一 messaging/notifications 的 type 定义

P0-12：users 模块硬编码弱密码

• 文件：src/modules/users/user-service.ts
• 行号：13
• 问题：const DEFAULT_PASSWORD = "123456" 硬编码弱密码，批量导入用户使用极弱默认密码
• 修复：改为随机生成密码或要求首次登录强制修改密码，至少使用 crypto.randomBytes 生成

P0-13：users/actions.ts updateUserProfile 绕过权限校验

• 文件：src/modules/users/actions.ts
• 行号：29-51
• 问题：updateUserProfile 使用 requireAuth() 而非 requirePermission()，且在 actions 层直接执行 db.update(users)，返回 Promise<void> 而非 ActionState<T>
• 修复：改为 requirePermission(Permissions.USER_MANAGE) 或新增 USER_PROFILE_UPDATE 权限点；DB 操作下沉到 data-access；返回 ActionState<void>

P0-14：scheduling/data-access.ts 缺返回类型标注

• 文件：src/modules/scheduling/data-access.ts
• 行号：239, 246, 255, 262
• 问题：getAdminClassesForScheduling()、getTeachersForScheduling()、getClassroomsForScheduling()、getClassSubjectsForScheduling() 缺少返回类型标注，违反"函数返回值必须显式标注，特别是 Promise"
• 修复：添加返回类型 : Promise<Array<{ id: string; name: string; grade: string }>> 等

---

三、按模块详细核查

3.1 exams（考试模块）

src/modules/exams/actions.ts（767 行）

行号范围	问题类别	严重程度	问题描述	改进建议
270	TS规范	P1	formData.get("questionsJson") as string | null — 使用 as 断言，非从 unknown 转换	改用 typeof 守卫：const raw = formData.get("questionsJson"); const rawQuestions = typeof raw === "string" ? raw : null
349-351	TS规范	P1	三处 as string | null 断言（questionsJson/aiQuestionsJson/structureJson）	统一使用 getStringValue() 辅助函数
4	TS规范	P2	import { ActionState } — 类型未使用 import type	改为 import type { ActionState }
564-565	Server Action规范	P2	JSON.parse(rawQuestions) 直接 parse 后传入 Zod，parse 异常未捕获	用 try-catch 包裹或先 as unknown 再 safeParse
全文件	行数	P2	实际 767 行，架构文档记录为 691 行，文档与代码不同步	同步更新 004 和 005 架构文档

合规项：所有 10 个 Action 均调用 requirePermission() ✓；均使用 Zod 验证 ✓；均返回 ActionState<T> ✓；均使用 revalidatePath ✓。

src/modules/exams/ai-pipeline.ts（912 行）

行号范围	问题类别	严重程度	问题描述	改进建议
全文件	行数	P2	912 行，超出 800 行建议（架构文档记录 857 行，已不同步）。混合 4 类职责	按职责拆分为 ai-json-parser.ts、ai-prompts.ts、ai-requests.ts、ai-preview-builder.ts
464	TS规范	P2	draft.sections!.forEach — 非空断言	改用 if (draft.sections) { draft.sections.forEach(...) }
657, 665, 666, 671	TS规范	P2	多处 aiParsed.sections!.flatMap / aiParsed.sections!.map — 非空断言	同上，用条件守卫替代
505, 508, 545, 879	TS规范	P2	as Record<string, unknown> — 虽然从 unknown 转换允许，但缺少注释说明原因	添加注释 // safe: validated by isRecord
557-558	代码质量	P2	catch {} 空捕获块，静默吞掉错误	至少记录 console.warn
503-524	代码质量	P2	normalizeQuestionCandidate 嵌套定义在 parseQuestionDetail 内部，每次调用都重新创建闭包	提取为模块级函数

合规项：使用 mapWithConcurrency 实现并发控制 ✓；使用 Promise.all ✓；env.AI_MODEL 服务端环境变量无 NEXT_PUBLIC_ 前缀 ✓。

src/modules/exams/data-access.ts（524 行）

行号范围	问题类别	严重程度	问题描述	改进建议
2, 318	架构违规	P0	persistAiGeneratedExamDraft 直接 db.insert(questions) 写入 questions 表	改为调用 questions/data-access.createQuestionWithRelations()
2, 72-80, 156-163, 357-364	架构违规	P0	getExams/getExamById/getExamsDashboardStats 直接查询 classes 表	在 classes 模块暴露 getGradeIdsByClassIds(classIds) 接口
2, 206-226, 509-524	架构违规	P1	resolveSubjectGradeNames/getExamSubjects/getExamGrades 直接查询 subjects/grades 表	在 school 模块暴露 getSubjectOptions()/getGradeOptions() 接口
76, 160, 361	TS规范	P1	teacherGradeIds.map(g => g.gradeId).filter(Boolean) as string[] — as 断言	使用类型守卫：.filter((id): id is string => Boolean(id))
108, 172	TS规范	P2	(exam.status as ExamStatus) — as 断言从 string 转换	使用 z.enum() 验证或类型守卫函数
182	TS规范	P2	exam.structure as unknown — 转换到 unknown 允许，但无注释	添加注释说明

合规项：使用 cache() 包装查询函数 ✓；使用 Promise.all 并行查询 ✓；使用 Map 做 O(1) 查找 ✓。

src/modules/exams/types.ts（31 行）

无违规问题。类型定义规范，接口命名 PascalCase 无 I 前缀 ✓。

---

3.2 homework（作业模块）

src/modules/homework/actions.ts（282 行）

行号范围	问题类别	严重程度	问题描述	改进建议
247	TS规范	P1	formData.get("answersJson") as string | null — as 断言	改用 typeof 守卫
54	TS规范	P2	JSON.parse(targetStudentIdsJson) as unknown — 转换到 unknown 允许，但无注释	添加注释

合规项：所有 5 个 Action 均调用 requirePermission() ✓；使用 Zod 验证 ✓；返回 ActionState ✓；使用 revalidatePath ✓；使用 Set 做查找 ✓。

src/modules/homework/data-access.ts（681 行）

行号范围	问题类别	严重程度	问题描述	改进建议
8-20, 101-105, 162-166, 283-287, 337-340, 518-519	架构违规	P1	直接查询 exams 表（5 处），属 exams 模块	在 exams 模块暴露 getExamIdsByGradeIds(gradeIds) 接口
8-20, 66-77, 86-95, 149-158, 242-254, 275-281, 347-351	架构违规	P1	直接查询 classEnrollments 表（多处），属 classes 模块	在 classes 模块暴露 getStudentIdsByClassId(classId) / getStudentIdsByClassIds(classIds) 接口
8-20, 515-519	架构违规	P1	直接查询 subjects 表，属 school 模块	通过 school data-access 获取
8-20, 480-486	架构违规	P1	直接查询 users/roles/usersToRoles 表，属 users 模块	在 users 模块暴露 getUserWithRole(userId, roleName) 接口
475-490	架构违规	P2	getDemoStudentUser 使用 auth() 而非 getAuthContext()，绕过 auth-guard 标准模式	改用 getAuthContext() 获取 userId
39	TS规范	P1	return v as HomeworkQuestionContent — 从 Record<string, unknown> 断言	使用类型守卫或 z.safeParse() 验证
124, 226, 314, 392, 467, 645	TS规范	P2	多处 (status as HomeworkAssignmentStatus) — as 断言	使用类型守卫函数或 Zod 验证
451-455	性能	P2	getHomeworkSubmissionDetails 获取全部 submissions 仅为计算 prev/next 导航	改用 SQL LAG/LEAD 窗口函数或仅查询相邻 ID

合规项：使用 cache() ✓；使用 Map/Set 聚合 ✓；"server-only" 导入 ✓。

src/modules/homework/data-access-write.ts（317 行）

行号范围	问题类别	严重程度	问题描述	改进建议
8-17, 70-76, 125-130	架构违规	P1	直接查询 classes 表（getClassTeacherById）	在 classes 模块暴露 getClassTeacherById(classId) 接口
8-17, 132-143	架构违规	P1	直接查询 classEnrollments 表（getActiveClassStudentIdsForHomework）	在 classes 模块暴露 getActiveStudentIdsByClassId(classId) 接口
8-17, 107-116	架构违规	P1	直接查询 classSubjectTeachers 表	在 classes 模块暴露 getTeacherSubjectIdsByClass(classId, teacherId) 接口
8-17, 81-88	架构违规	P1	直接查询 exams 表（getExamWithQuestionsForHomework）	在 exams 模块暴露 getExamForHomeworkCreation(examId) 接口
305-311	性能	P2	gradeHomeworkAnswers 中 for (const ans of answers) { await db.update(...) } — 循环内串行 await，未使用事务	用 db.transaction 包裹，或用 Promise.all 并行化无依赖更新

合规项："server-only" 导入 ✓；所有函数显式标注返回类型 ✓；无 as/any ✓。

src/modules/homework/schema.ts（29 行）

无违规问题。Zod 验证完整 ✓。

src/modules/homework/stats-service.ts（483 行）

行号范围	问题类别	严重程度	问题描述	改进建议
8-16, 313-323, 320-323	架构违规	P1	直接查询 classEnrollments 表	通过 classes data-access 获取
8-16, 437-441	架构违规	P1	直接查询 classes 表	通过 classes data-access 获取
8-16, 425-429, 443-447	架构违规	P1	直接查询 exams 表	通过 exams data-access 获取
8-16, 366-369	架构违规	P1	直接查询 users 表	在 users 模块暴露 getUserNamesByIds(ids) 接口
220	TS规范	P2	(assignment.status as HomeworkAssignmentStatus) — as 断言	使用类型守卫
346	性能	P2	limit: 5000 查询班级所有 graded submissions，大班级可能性能问题	考虑分批查询或 SQL 聚合

合规项：使用 cache() ✓；使用 Promise.all 并行查询 ✓；使用 Map 聚合 ✓。

src/modules/homework/types.ts（205 行）

无违规问题。类型定义规范 ✓。

---

3.3 questions（题库模块）

src/modules/questions/actions.ts（176 行）

行号范围	问题类别	严重程度	问题描述	改进建议
154	Server Action规范	P0	getQuestionsAction 未返回 ActionState<T>，直接返回 getQuestions(params) 的原始结果 { data, meta }，错误时 throw	改为 Promise<ActionState<...>> 返回 { success: true, data: result }
166-175	Server Action规范	P0	getKnowledgePointOptionsAction 未返回 ActionState<T>，直接返回 KnowledgePointOption[]	同上，包装为 ActionState
154	TS规范	P1	getQuestionsAction 缺少显式返回类型标注	添加 : Promise<ActionState<...>>
7	TS规范	P2	import { ActionState } — 类型导入未用 import type	改为 import type { ActionState }
158-163, 170-175	代码质量	P2	catch 块两个分支都 throw e，是死代码	简化为单个 throw e 或返回失败 ActionState
20	命名规范	P2	函数名 createNestedQuestion 与其他模块的 createXxxAction 命名模式不一致	改为 createQuestionAction

合规项：所有 Action 调用 requirePermission() ✓；create/update/delete 使用 Zod 验证 ✓；写操作使用 revalidatePath ✓。

src/modules/questions/data-access.ts（299 行）

行号范围	问题类别	严重程度	问题描述	改进建议
4, 266-298	架构违规	P1	getKnowledgePointOptions 直接查询 knowledgePoints/chapters/textbooks 表，属 textbooks 模块	在 textbooks 模块暴露 getKnowledgePointOptions() 接口
108	代码质量	P2	局部变量名 knowledgePoints 与 import 的 knowledgePoints 表名冲突	重命名为 kpRows 或 kps
151-184, 231-242	性能	P2	insertQuestionWithRelations / deleteQuestionRecursive 递归内串行 await	对于删除可改为先收集所有 ID 再批量删除

合规项：使用 cache() ✓；"server-only" 导入 ✓；无 as/any ✓；显式返回类型 ✓。

src/modules/questions/schema.ts（18 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6	TS规范	P0	content: z.any() — 使用 any，违反"禁止 any"规则	改为 z.unknown()

src/modules/questions/types.ts（34 行）

无违规问题。content: unknown 正确使用 unknown ✓。

---

3.4 grades（成绩模块）

src/modules/grades/actions.ts（312 行）

行号范围	问题类别	严重程度	问题描述	改进建议
93	代码质量	P2	JSON.parse(recordsJson) 未用 try-catch 包裹，parse 失败会 500	用 try-catch 或先 as unknown 再 safeParse

合规项：所有 Action 调用 requirePermission() ✓；使用 Zod 验证 ✓；返回 ActionState<T> ✓；使用 revalidatePath ✓；scope 二次校验 ✓。

src/modules/grades/actions-analytics.ts（133 行）

合规项：所有 Action 调用 requirePermission() ✓；返回 ActionState<T> ✓；scope 二次校验 ✓。无违规问题。

src/modules/grades/data-access.ts（419 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6-12, 100, 382-386	架构违规	P1	直接查询 classes 表	通过 classes data-access 获取
6-12, 365-368, 408-411	架构违规	P1	直接查询 classEnrollments 表	通过 classes data-access 获取
6-12, 102, 276, 280	架构违规	P1	直接查询 subjects 表	通过 school data-access 获取
6-12, 100, 109-112, 269, 342	架构违规	P1	直接查询 users 表	通过 users data-access 获取
148, 172	性能	P1	const { createId } = await import("@paralleldrive/cuid2") — 函数内动态 import，每次调用都有开销	改为文件顶部静态 import { createId } from "@paralleldrive/cuid2"
249	代码质量/Bug	P1	const ratio = scores[i] / fullScores[i] — fullScores[i] 可能为 0，导致 Infinity/NaN	添加 if (fullScores[i] <= 0) continue 守卫
全文件	性能	P2	查询函数未使用 React.cache() 包装	用 cache() 包装查询函数
248-252	性能	P2	for 循环内两次独立 if 判断遍历同一数组	合并为单次循环同时计算 passCount 和 excellentCount

合规项："server-only" 导入 ✓；使用 Map/Set ✓；无 as/any ✓；显式返回类型 ✓。

src/modules/grades/data-access-analytics.ts（293 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6-10, 79, 125-128	架构违规	P1	直接查询 classes 表	通过 classes data-access 获取
6-10, 80, 211	架构违规	P1	直接查询 subjects 表	通过 school data-access 获取
22, 27, 32	代码质量	P2	toNumber/normalize/buildScopeClassFilter 在 data-access.ts 和 data-access-ranking.ts 中重复定义	提取到 grades/utils.ts
142-185	性能	P0	getClassComparison 中 for (const cls of classRows) { ... await db.select(...) } — 循环内串行查询，N+1 问题	用 inArray 一次性查询所有班级的成绩，再在内存分组
133-136	性能	P2	classRows.filter((c) => scope.classIds.includes(c.id)) — includes 是 O(n) 查找	将 scope.classIds 转为 Set 后用 .has()
180-181, 238-239	性能	P2	normalized.filter((s) => s >= 60).length 和 normalized.filter((s) => s >= 85).length — 两次 filter 遍历同一数组	合并为单次 reduce 同时统计两个计数
全文件	性能	P2	查询函数未使用 React.cache()	用 cache() 包装

合规项："server-only" ✓；无 as/any ✓；显式返回类型 ✓。

src/modules/grades/data-access-ranking.ts（121 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6-10, 44-53	架构违规	P1	直接查询 classEnrollments 表	通过 classes data-access 获取
6-10, 37-41	架构违规	P1	直接查询 users 表	通过 users data-access 获取
17, 22	代码质量	P2	toNumber/normalize 重复定义	提取到共享 utils
100, 102	性能	P2	sorted.findIndex(...) 和 sorted.find(...) 两次 O(n) 查找同一元素	合并为一次遍历
全文件	性能	P2	查询函数未使用 React.cache()	用 cache() 包装

src/modules/grades/export.ts（214 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6-11, 116-120	架构违规	P1	直接查询 classes 表	通过 classes data-access 获取
6-11, 124-132	架构违规	P1	直接查询 subjects 表	通过 school data-access 获取
6-11, 135-144	架构违规	P1	直接查询 users 表	通过 users data-access 获取
154	TS规范	P2	subjMap.get(r.studentId)! — 非空断言	改用 const subjMap = scoreMap.get(r.studentId); if (!subjMap) continue;

src/modules/grades/schema.ts（52 行）& types.ts（176 行）

无违规问题。Zod 验证完整，类型定义规范 ✓。

---

3.5 textbooks（教材模块）

src/modules/textbooks/actions.ts（276 行）

行号范围	问题类别	严重程度	问题描述	改进建议
全文件	Server Action规范	P0	缺少 schema.ts 文件，所有 Action 均无 Zod 验证，使用手动 if (!rawData.title) 检查	新建 schema.ts，为每个 Action 定义 Zod schema
41-45	架构违规	P1	本地定义 export type ActionState，未使用 @/shared/types/action-state 的统一类型	删除本地定义，改用 import type { ActionState } from "@/shared/types/action-state"
18	TS规范	P1	import { CreateTextbookInput, UpdateTextbookInput } — 类型导入未用 import type	改为 import type { ... }
54-58, 92-98, 154, 219-221, 259-261	TS规范	P0	多处 formData.get("title") as string 等 as 断言（共 14 处）	改用 typeof 守卫或 getStringValue() 辅助函数
20, 47	代码质量	P2	// ... existing code ... 残留注释	删除
164	代码质量	P2	order: 0 // Default order 魔法数字	提取为常量 const DEFAULT_CHAPTER_ORDER = 0

合规项：所有 Action 调用 requirePermission() ✓；使用 revalidatePath ✓。

src/modules/textbooks/data-access.ts（444 行）

行号范围	问题类别	严重程度	问题描述	改进建议
42	TS规范	P2	byId.get(pid)!.children.push(ch) — 非空断言	改用 const parent = byId.get(pid); if (parent) parent.children.push(ch)
51	TS规范	P1	sortRecursive(n.children as Array<Chapter & { children: Chapter[] }>) — as 断言	使用类型守卫或在 Chapter 类型中明确 children 字段
71	TS规范	P2	or(...)! — 对 or() 返回值使用非空断言	改用条件判断
110, 128	代码质量	P2	getTextbookById 返回 Textbook | undefined，与其他模块返回 null 的模式不一致	统一返回 Textbook | null
368, 381	代码质量	P2	createKnowledgePoint/updateKnowledgePoint 参数使用内联类型	将输入类型移至 types.ts

合规项：使用 cache() ✓；使用 Promise.all ✓；"server-only" ✓；无 any ✓；显式返回类型 ✓。这是架构文档中的"标杆模块"，无跨模块 DB 访问 ✓。

src/modules/textbooks/types.ts（83 行）

行号范围	问题类别	严重程度	问题描述	改进建议
1-3	代码质量	P2	残留注释 // In a real app, we would infer these from the schema...	删除过时注释

---

3.6 classes（班级模块）

src/modules/classes/actions.ts（765 行）

行号范围	问题类别	严重程度	问题描述	改进建议
8-9	架构违规	P0	actions 层直接导入 db 和 grades, classes schema 并执行 DB 查询	将权限校验查询下沉到 data-access-admin.ts
48-53, 109-111, 140-142, 175-183, 369-377, 518-533, 636-644	Server Action规范	P1	输入验证使用手动 typeof 检查而非 Zod，classes 模块完全没有 schema.ts 文件	新建 schema.ts，定义 Zod schema
538	TS规范	P1	weekdayNum as 1 | 2 | 3 | 4 | 5 | 6 | 7 — as 断言	用类型守卫 isValidWeekday(weekdayNum): weekdayNum is 1|2|3|4|5|6|7 替换
582	TS规范	P1	weekdayNum as 1 | 2 | 3 | 4 | 5 | 6 | 7 | undefined — 同上	同上
287, 706	TS规范	P2	JSON.parse(subjectTeachers) as unknown 后续用 as { subject?: unknown }	用 Zod schema 解析

src/modules/classes/data-access.ts（656 行）

行号范围	问题类别	严重程度	问题描述	改进建议
26-27, 182-206	架构违规	P0	getTeacherClasses 中调用 getClassHomeworkInsights（homework 逻辑）和 getClassSchedule（scheduling 逻辑）	将 homework insights 聚合逻辑移至 homework 模块
47	TS规范	P1	isDuplicateInvitationCodeError 箭头函数缺少返回类型标注	添加 : boolean
54	TS规范	P1	generateInvitationCode 箭头函数缺少返回类型标注	添加 : string
87	TS规范	P1	normalizeSortText 箭头函数缺少返回类型标注	添加 : string
89	TS规范	P1	parseFirstInt 箭头函数缺少返回类型标注	添加 : number | null
94	TS规范	P1	compareGradeLabel 箭头函数缺少返回类型标注	添加 : number
101-104	TS规范	P1	compareClassLike 箭头函数缺少返回类型标注	添加 : number
240	TS规范	P1	r.subject as ClassSubject — as 断言	用类型守卫 isClassSubject(r.subject) 过滤
266	TS规范	P1	r.name as ClassSubject — 同上	同上
287	TS规范	P2	idByName.get(name)! — 非空断言	用 const id = idByName.get(name); if (!id) return null 显式处理
297-299	代码质量	P1	throw new Error("Failed to create class") 后有 return id 不可达代码	删除 return id
561	TS规范	P1	r.name as ClassSubject — as 断言	用类型守卫替换
567	TS规范	P2	idByName.get(name)! — 非空断言	显式判空处理
120-127	性能	P2	getAccessibleClassIdsForTeacher 中两个独立 DB 查询串行执行	用 Promise.all 并行化

src/modules/classes/data-access-admin.ts（441 行）

行号范围	问题类别	严重程度	问题描述	改进建议
82-117, 237-239	代码质量	P1	try-catch 吞掉错误返回空数组或 fallback 查询	移除 try-catch 或记录错误日志后 rethrow
135	TS规范	P1	r.subject as ClassSubject — as 断言	用类型守卫替换
259	TS规范	P1	r.subject as ClassSubject — 同上	同上
303	TS规范	P1	getManagedGrades 缺少返回类型标注	添加 : Promise<GradeListItem[]>
349	TS规范	P1	r.name as ClassSubject — as 断言	用类型守卫替换
369	TS规范	P2	idByName.get(name)! — 非空断言	显式判空
380-382	代码质量	P1	throw new Error("Failed to create class") 后有 return id 不可达代码	删除 return id

src/modules/classes/data-access-schedule.ts（230 行）

行号范围	问题类别	严重程度	问题描述	改进建议
7-11, 33-48	架构违规	P1	直接导入并查询 classSchedule 表（该表归属 scheduling 模块）	将读取也委托给 scheduling 模块的 data-access
54	TS规范	P1	r.weekday as StudentScheduleItem["weekday"] — as 断言	用类型守卫或 Zod 校验 weekday 范围
93	TS规范	P1	r.weekday as ClassScheduleItem["weekday"] — 同上	同上

src/modules/classes/data-access-stats.ts（604 行）

行号范围	问题类别	严重程度	问题描述	改进建议
11-18	架构违规	P0	直接导入并查询 homeworkAssignmentQuestions、homeworkAssignmentTargets、homeworkAssignments、homeworkSubmissions、exams 等 homework/exams 模块的 DB 表	通过 homework 模块的 data-access 暴露的函数获取数据
250	TS规范	P1	(s.status ?? "started") as string — as 断言	s.status 已是 string 类型，无需断言
261	TS规范	P1	(a.status as string) ?? "draft" — as 断言	同上
512	TS规范	P1	(s.status ?? "started") as string — 同上	同上
523	TS规范	P1	(a.status as string) ?? "draft" — 同上	同上
130-151, 175-191	性能	P2	多个早期返回中重复构造相同的返回对象结构	提取 buildEmptyInsights(classRow, studentCounts) 工厂函数

src/modules/classes/data-access-students.ts（280 行）

行号范围	问题类别	严重程度	问题描述	改进建议
10-14	架构违规	P0	直接导入并查询 homeworkAssignmentTargets、homeworkAssignments、homeworkSubmissions、exams 等 homework/exams 模块的 DB 表	通过 homework 模块 data-access 获取数据
102	TS规范	P2	studentScores.get(s.studentId)! — 非空断言	显式判空处理
168-204	代码质量	P2	getStudentClasses 中 try-catch fallback 查询使用 sql\NULL`.as(...)` 模式，吞掉错误	移除 try-catch

src/modules/classes/types.ts（201 行）

基本符合规范，无违规问题。

---

3.7 school（学校模块）

src/modules/school/actions.ts（325 行）

行号范围	问题类别	严重程度	问题描述	改进建议
7-8, 26-30, 53-59, 73, 96-108, 133-147, 161, 182-186, 211-217, 233, 261-268, 294-303, 317	架构违规	P0	actions 层直接导入 db 和所有 schema，所有 mutation 直接操作 DB，完全没有下沉到 data-access 层	在 data-access.ts 中新增 createDepartment、updateDepartment、deleteDepartment、createSchool 等函数
188, 219, 235	性能	P2	await logAudit(...) 阻塞响应，审计日志写入是非关键路径	使用 Next.js after() 函数将 logAudit 改为非阻塞执行

src/modules/school/data-access.ts（186 行）

行号范围	问题类别	严重程度	问题描述	改进建议
13, 27, 44, 59, 112, 133	代码质量	P2	所有函数都用 try-catch 包裹并返回空数组 [] 吞掉错误	移除 try-catch 或记录错误日志后 rethrow

src/modules/school/schema.ts（51 行）& types.ts（42 行）

符合规范。

---

3.8 scheduling（排课模块）

src/modules/scheduling/actions.ts（300 行）

行号范围	问题类别	严重程度	问题描述	改进建议
10-11, 112-116	架构违规	P0	actions 层直接导入 db 和 users schema，在 autoScheduleAction 中直接查询 users 表获取教师信息	在 data-access.ts 中新增 getTeachersByIds(teacherIds: string[]) 函数
115	TS规范	P1	teacherIds[0]! — 非空断言	用条件表达式 eq(users.id, teacherIds[0] ?? "")

src/modules/scheduling/auto-scheduler.ts（310 行）

行号范围	问题类别	严重程度	问题描述	改进建议
144-145	TS规范	P1	schedule[i]!、schedule[j]! — 非空断言	用局部变量 + 显式判空
全文件	行数	P2	工具函数规范要求 ≤ 40 行，此文件 310 行	拆分为 auto-scheduler/ 目录下的多个文件

src/modules/scheduling/data-access.ts（368 行）

行号范围	问题类别	严重程度	问题描述	改进建议
239	TS规范	P0	getAdminClassesForScheduling() 缺少返回类型标注	添加返回类型
246	TS规范	P0	getTeachersForScheduling() 缺少返回类型标注	添加返回类型
255	TS规范	P0	getClassroomsForScheduling() 缺少返回类型标注	添加返回类型
262	TS规范	P0	getClassSubjectsForScheduling(classId: string) 缺少返回类型标注	添加返回类型
113-114	代码质量	P2	requesterName: users.name 与 originalTeacherName: users.name 选中同一列，requesterName 在 map 中被 userMap.get() 覆盖，select 中的字段是死代码	删除 select 中的 requesterName: users.name
140	TS规范	P1	userIds[0]! — 非空断言	显式判空
221-222	TS规范	P1	rows[i]!、rows[j]! — 非空断言	用局部变量 + 显式判空

src/modules/scheduling/schema.ts（81 行）& types.ts（124 行）

符合规范。

---

3.9 attendance（考勤模块）

src/modules/attendance/actions.ts（271 行）

基本符合规范。所有 action 调用了 requirePermission、使用 Zod 验证、返回 ActionState、使用 revalidatePath。

src/modules/attendance/data-access.ts（271 行）

行号范围	问题类别	严重程度	问题描述	改进建议
195	TS规范	P1	const update: Record<string, unknown> = { updatedAt: new Date() } — 使用宽泛的 Record<string, unknown> 丢失类型安全	使用 Partial<typeof attendanceRecords.$inferSelect> 类型

src/modules/attendance/data-access-stats.ts（145 行）& schema.ts（43 行）& types.ts（103 行）

符合规范。

---

3.10 course-plans（教学计划模块）

src/modules/course-plans/actions.ts（265 行）

行号范围	问题类别	严重程度	问题描述	改进建议
236-246	Server Action规范	P1	deleteCoursePlanItemAction 未调用 revalidatePath	添加 revalidatePlanPaths() 调用
248-264	Server Action规范	P1	toggleCoursePlanItemCompletedAction 未调用 revalidatePath	同上

src/modules/course-plans/data-access.ts（320 行）

行号范围	问题类别	严重程度	问题描述	改进建议
149	TS规范	P1	params.status as CoursePlanStatus — as 断言	用类型守卫或 Zod 校验
158, 183	代码质量	P2	getCoursePlans 和 getCoursePlanById 用 try-catch 返回空数组/null 吞掉错误	移除 try-catch 或记录日志后 rethrow
300-305	性能	P2	reorderCoursePlanItems 中循环内串行 await db.update()，N 次 DB 往返	用 db.transaction 批量更新，或用 Promise.all 并行化

src/modules/course-plans/schema.ts（148 行）& types.ts（60 行）

符合规范。

---

3.11 users（用户模块）

src/modules/users/actions.ts（151 行）

行号范围	问题类别	严重程度	问题描述	改进建议
29-51	Server Action规范	P0	updateUserProfile 使用 requireAuth() 而非 requirePermission()	改为 requirePermission(Permissions.USER_MANAGE) 或新增 USER_PROFILE_UPDATE 权限点
29-51	架构违规	P1	updateUserProfile 在 actions 层直接执行 db.update(users)	将写操作下沉到 data-access.ts
29-51	Server Action规范	P1	updateUserProfile 返回 Promise<void> 而非 ActionState<T>	改为返回 Promise<ActionState<void>>
29	TS规范	P2	updateUserProfile(data: UpdateUserProfileInput) 缺少显式返回类型标注	标注为 Promise<ActionState<void>>
29-51	Server Action规范	P2	updateUserProfile 输入未使用 Zod 验证	新增 Zod schema
76-125	Server Action规范	P2	importUsersAction 输入验证使用手动逻辑，未使用 Zod	将 parseUserImportData 改用 Zod 实现

src/modules/users/class-registration.ts（27 行）

合规，无违规问题。正确通过 classes/data-access.enrollStudentByInvitationCode 跨模块通信。

src/modules/users/data-access.ts（152 行）

行号范围	问题类别	严重程度	问题描述	改进建议
24	命名规范	P2	const rolePriority 常量未使用 UPPER_SNAKE_CASE	重命名为 ROLE_PRIORITY
26-31	架构违规	P2	normalizeRoleName 与 shared/lib/role-utils.ts 的 normalizeRole 重复	改为 import { normalizeRole } from "@/shared/lib/role-utils" 复用
26	TS规范	P2	normalizeRoleName 缺少显式返回类型标注	标注为 (value: string) => string
33	TS规范	P2	resolvePrimaryRole 缺少显式返回类型标注	标注为 (roleNames: string[]) => string

src/modules/users/import-export.ts（176 行）

行号范围	问题类别	严重程度	问题描述	改进建议
98	TS规范	P2	const conditions = [] 隐式推断为 any[]，违反"禁止 any"规则	标注类型 const conditions: ReturnType<typeof eq>[] = []
100-114	性能	P2	exportUsersToExcel 中 role 查询 → userIds 查询 → users 查询为串行	可接受（有依赖关系），但建议合并为子查询减少往返

src/modules/users/user-service.ts（99 行）

行号范围	问题类别	严重程度	问题描述	改进建议
13	安全规范	P0	const DEFAULT_PASSWORD = "123456" 硬编码弱密码	改为随机生成密码或要求首次登录强制修改密码
15-19	架构违规	P2	normalizeBcryptHash 与 shared/lib/bcrypt-utils.ts 重复	改为 import { normalizeBcryptHash } from "@/shared/lib/bcrypt-utils" 复用
15	TS规范	P2	normalizeBcryptHash 缺少显式返回类型标注	标注为 (value: string) => string
30-92	架构违规	P1	batchImportUsers 注释标注"批量导入用户（事务）"，但实际未使用 db.transaction 包裹	用 await db.transaction(async (tx) => { ... }) 包裹
50-92	性能	P2	循环内串行 await db.insert，N 条记录需 N 次 DB 往返	可批量插入用户和角色关联

---

3.12 messaging（消息模块）

src/modules/messaging/actions.ts（247 行）

行号范围	问题类别	严重程度	问题描述	改进建议
163	Server Action规范	P1	getNotificationsAction 使用 requireAuth() 而非 requirePermission()	改为 requirePermission(Permissions.MESSAGE_READ)
177	Server Action规范	P1	markNotificationAsReadAction 使用 requireAuth() 而非 requirePermission()	同上
190	Server Action规范	P1	markAllNotificationsAsReadAction 使用 requireAuth() 而非 requirePermission()	同上
203	Server Action规范	P1	getNotificationPreferencesAction 使用 requireAuth() 而非 requirePermission()	同上
218	Server Action规范	P1	updateNotificationPreferencesAction 使用 requireAuth() 而非 requirePermission()	同上
213-247	Server Action规范	P2	updateNotificationPreferencesAction 未使用 Zod 验证	新增 Zod schema 校验 8 个布尔字段
87, 101, 129	Server Action规范	P2	markMessageAsReadAction/deleteMessageAction/getMessageDetailAction 参数 messageId 未使用 Zod 验证	新增 z.string().min(1) 校验 messageId

src/modules/messaging/data-access.ts（252 行）

行号范围	问题类别	严重程度	问题描述	改进建议
12-14	架构违规	P1	导入 classEnrollments, classes，getRecipients（227-251 行）直接 JOIN 跨模块表	通过 classes/data-access 暴露 getStudentsByClassIds(classIds) 接口
94	TS规范	P2	const conds = [] 隐式 any[]	标注 drizzle 条件类型
97	TS规范	P2	or(...)! 使用非空断言	改为显式处理 null
117	TS规范	P2	or(...)! 使用非空断言	同上
163	TS规范	P2	or(...)! 使用非空断言	同上
63	TS规范	P2	mapMessage 缺少显式返回类型标注	标注返回类型
77	TS规范	P2	mapNotification 缺少显式返回类型标注	标注返回类型
80	TS规范	P2	r.type as NotificationType 使用 as 断言	使用类型守卫
74, 85	TS规范	P2	toIso(r.createdAt) as string 使用 as 断言	处理 null 情况或修改 toIso 返回类型
192-203	架构违规	P0	createNotification 写 messageNotifications 表，但 notifications 模块反向调用此函数，形成循环依赖	将 messageNotifications 表所有权移交 notifications 模块

src/modules/messaging/notification-preferences.ts（166 行）

行号范围	问题类别	严重程度	问题描述	改进建议
14	TS规范	P2	toIso 缺少显式返回类型标注	标注为 (d: Date) => string
16	TS规范	P2	mapRow 缺少显式返回类型标注	标注返回类型

src/modules/messaging/schema.ts（18 行）& types.ts（108 行）

合规，无违规问题。

---

3.13 notifications（通知模块）

src/modules/notifications/actions.ts（119 行）

行号范围	问题类别	严重程度	问题描述	改进建议
14-17	架构违规	P1	actions 层直接导入 db、classEnrollments、classes	将 DB 查询下沉到 data-access.ts
83-96	架构违规	P1	sendClassNotificationAction 直接查询 classes 和 classEnrollments 表	通过 classes/data-access 暴露查询接口
30-52	Server Action规范	P2	sendNotificationAction 参数 payload 未使用 Zod 验证	新增 NotificationPayloadSchema
62-119	Server Action规范	P2	sendClassNotificationAction 参数 classId/payload 未使用 Zod 验证	新增 Zod schema 校验

src/modules/notifications/data-access.ts（86 行）

行号范围	问题类别	严重程度	问题描述	改进建议
20	架构违规	P0	import { getNotificationPreferences } from "@/modules/messaging/notification-preferences" 反向依赖 messaging 模块	将 notificationPreferences 表所有权移交 notifications 模块
21	架构违规	P0	import type { NotificationPreferences } from "@/modules/messaging/types" 反向依赖 messaging 模块	类型定义应迁移到 notifications 模块
71-77	架构违规	P2	logNotificationSend 仅 console.info，无 DB 持久化	新增 notification_logs 表并写入发送结果

src/modules/notifications/dispatcher.ts（152 行）

行号范围	问题类别	严重程度	问题描述	改进建议
44	TS规范	P2	getSenders 缺少显式返回类型标注	标注为 () => SenderRegistry
59	TS规范	P2	selectChannels 缺少显式返回类型标注	标注返回类型

src/modules/notifications/external-sdk.d.ts（47 行）

行号范围	问题类别	严重程度	问题描述	改进建议
12, 20, 25, 33, 42, 43	TS规范	P2	多处使用 any（const _default: any、config: any、options: any）	安装实际 SDK 后用其自带类型覆盖；或使用 unknown

src/modules/notifications/index.ts（38 行）& types.ts（70 行）& channels/types.ts（38 行）

合规，无违规问题。

src/modules/notifications/channels/email-channel.ts（183 行）

行号范围	问题类别	严重程度	问题描述	改进建议
29	TS规范	P2	getEmailConfig 缺少显式返回类型标注	标注返回类型
45	TS规范	P2	getTypeColor 缺少显式返回类型标注	标注为 (type: NotificationPayload["type"]) => string
60	TS规范	P2	buildHtmlContent 缺少显式返回类型标注	标注为 (payload: NotificationPayload) => string
79	TS规范	P2	escapeHtml 缺少显式返回类型标注	标注为 (text: string) => string

src/modules/notifications/channels/in-app-channel.ts（88 行）

行号范围	问题类别	严重程度	问题描述	改进建议
50	架构违规	P0	await import("@/modules/messaging/data-access") 动态 import messaging 模块，运行时形成循环	将 messageNotifications 表所有权移交 notifications
54	TS规范	P1	payload.type as "message" | "announcement" | "homework" | "grade" 使用 as 断言，且源类型与目标类型不兼容，as 断言非法	重新设计类型映射函数

src/modules/notifications/channels/sms-channel.ts（236 行）

行号范围	问题类别	严重程度	问题描述	改进建议
30	TS规范	P2	getSmsConfig 缺少显式返回类型标注	标注返回类型
32	TS规范	P2	(process.env.SMS_PROVIDER ?? "mock") as "aliyun" | "tencent" | "mock" 使用 as 断言	使用类型守卫或 Zod 校验环境变量
44	TS规范	P2	buildTemplateParams 缺少显式返回类型标注	标注返回类型

src/modules/notifications/channels/wechat-channel.ts（208 行）

行号范围	问题类别	严重程度	问题描述	改进建议
40	TS规范	P2	getWechatConfig 缺少显式返回类型标注	标注返回类型
99	TS规范	P2	buildTemplateData 缺少显式返回类型标注	标注返回类型

---

3.14 parent（家长模块）

src/modules/parent/data-access.ts（234 行）

行号范围	问题类别	严重程度	问题描述	改进建议
59-105	架构违规	P1	getChildBasicInfo 直接查询 users、grades、classEnrollments、classes 表	通过 users/data-access.getUserProfile、classes/data-access 等接口查询
58	TS规范	P2	getChildBasicInfo 缺少显式返回类型标注	标注返回类型
30	TS规范	P2	(day === 0 ? 7 : day) as 1 | 2 | 3 | 4 | 5 | 6 | 7 使用 as 断言	使用类型守卫 function isWeekday(n: number): n is 1|2|3|4|5|6|7
58-117	性能	P2	getChildBasicInfo 串行查询 student → grade → enrollment → class	使用 JOIN 合并为单次查询，或用 Promise.all 并行化

src/modules/parent/types.ts（57 行）

合规，无违规问题。

---

3.15 audit（审计模块）

src/modules/audit/actions.ts（212 行）

行号范围	问题类别	严重程度	问题描述	改进建议
6, 70-100, 120-146, 166-192	架构违规	P2	Excel 导出逻辑内联在 actions 层	新建 audit/export.ts，将 Excel 构建逻辑迁移
63-205	架构违规	P2	三个导出 Action 结构高度重复	抽取通用 buildExcelSheet(name, columns, rows) 辅助函数
207-212	架构违规	P2	formatDateForFile 工具函数定义在 actions.ts 中	迁移到 shared/lib/utils.ts 或 audit/utils.ts
24-61	Server Action规范	P2	getDataChangeLogsAction 参数 params 未使用 Zod 验证	新增 DataChangeLogQueryParamsSchema
63-205	Server Action规范	P2	三个导出 Action 参数未使用 Zod 验证	新增对应 Zod schema

src/modules/audit/data-access.ts（260 行）

行号范围	问题类别	严重程度	问题描述	改进建议
18	TS规范	P2	toIso 缺少显式返回类型标注	标注为 (d: Date) => string
23	TS规范	P2	clampPageSize 缺少显式返回类型标注	标注为 (size?: number) => number
28	TS规范	P2	clampPage 缺少显式返回类型标注	标注为 (page?: number) => number
40, 95, 158	TS规范	P2	const conditions = [] 隐式 any[]	标注 drizzle 条件类型
75	TS规范	P2	r.status as "success" | "failure" 使用 as 断言	使用类型守卫
122	TS规范	P2	r.action as "signin" | "signout" | "signup" 使用 as 断言	使用类型守卫
123	TS规范	P2	r.status as "success" | "failure" 使用 as 断言	使用类型守卫
186	TS规范	P2	r.action as "create" | "update" | "delete" 使用 as 断言	使用类型守卫
50-86, 104-137, 168-202	安全/质量	P2	getAuditLogs/getLoginLogs/getDataChangeLogs 使用 try-catch 吞错误返回空数组	至少 console.error 记录错误
235-240	逻辑错误	P1	getAuditLogsForExport 注释标注 "no pagination cap"，但实际调用 getAuditLogs({ page: 1, pageSize: 100 })，最多只返回 100 条，导出数据不完整	实现真正的无分页查询，或循环分页拉取全部数据
245-250	逻辑错误	P1	getLoginLogsForExport 同上问题，最多 100 条	同上
255-260	逻辑错误	P1	getDataChangeLogsForExport 同上问题，最多 100 条	同上

src/modules/audit/types.ts（91 行）

合规，无违规问题。

---

3.16 elective（选修课模块）

src/modules/elective/data-access.ts

行号范围	问题类别	严重程度	问题描述	改进建议
117	TS规范	P1	params.status as ElectiveCourseStatus 使用 as 断言	直接使用 params.status，无需断言
78	TS规范	P2	buildCourseSelect = () => 箭头函数缺少显式返回类型标注	添加返回类型标注
136-138, 150-152	代码质量	P2	catch { return [] / null } 静默吞掉异常	至少 console.error 记录错误

src/modules/elective/data-access-selections.ts

行号范围	问题类别	严重程度	问题描述	改进建议
102	TS规范	P1	r.status as CourseSelectionStatus 使用 as 断言	应通过类型守卫或直接赋值
114	TS规范	P1	r.courseStatus as ElectiveCourseStatus | null 同上	同上
59, 117	TS规范	P2	buildCourseSelect 和 selectionDetailSelect 箭头函数缺少显式返回类型	添加返回类型标注
7-14	架构违规	P1	直接导入并查询 classes、classEnrollments 表	通过 @/modules/classes/data-access 暴露的函数获取
全文件	性能	P2	均未用 React.cache() 包裹	对读函数用 cache() 包裹

src/modules/elective/data-access-operations.ts

行号范围	问题类别	严重程度	问题描述	改进建议
18-34	性能	P2	runLottery 中先查 course 再查 selections，两次独立查询串行 await	用 Promise.all 并行
46-71	性能	P1	for 循环内逐条 await db.update()，N 名学生产生 N 次 DB 往返	拆分为两组 ID，用 inArray 执行 2 次批量 UPDATE
46-76	安全/数据完整性	P1	runLottery 多步更新未包裹事务	使用 db.transaction() 包裹整个摇号流程
86-112	性能	P2	selectCourse 中查 course 和查 existing selection 两次独立查询串行	用 Promise.all 并行
158-182	性能	P2	dropCourse 中查 existing 和查 course 串行	并行化独立查询

src/modules/elective/schema.ts（20-24 行）

行号范围	问题类别	严重程度	问题描述	改进建议
20-24	TS规范	P2	emptyToNull 和 optionalStringToNull 箭头函数缺少显式返回类型	添加返回类型

src/modules/elective/types.ts

未发现违规问题。

src/modules/elective/actions.ts

行号范围	问题类别	严重程度	问题描述	改进建议
278-294	Server Action规范	P2	getStudentSelectionsAction(studentId: string) 直接接收参数，未经 Zod 校验	对 studentId 用 Zod 校验

---

3.17 proctoring（监考模块）

src/modules/proctoring/actions.ts

行号范围	问题类别	严重程度	问题描述	改进建议
11-13, 79-84	架构违规	P0	actions.ts（编排层）直接导入 db、examSubmissions 并执行 DB 查询	将 submission 归属校验逻辑移至 data-access.ts
3	TS规范	P1	import { ActionState } 应为 import type { ActionState }	改为 import type { ActionState }
39	TS规范	P1	as z.ZodType<ProctoringEventType> 使用 as 断言	直接使用 z.enum([...]) 推导
63	Server Action规范	P1	recordProctoringEventAction 使用 requireAuth() 而非 requirePermission()	使用 requirePermission(Permissions.EXAM_SUBMIT)
全文件	Server Action规范	P2	recordProctoringEventAction 未调用 revalidatePath	添加 revalidatePath 刷新监考面板相关路径

src/modules/proctoring/data-access.ts

行号范围	问题类别	严重程度	问题描述	改进建议
127	TS规范	P1	row.event.eventType as ProctoringEventType 使用 as 断言	drizzle enum 列类型已是字面量联合，应直接匹配
152	TS规范	P1	row.eventType as ProctoringEventType 同上	同上
208	TS规范	P1	stat.eventType as ProctoringEventType 同上	同上
290	TS规范	P1	row.eventType as ProctoringEventType 同上	同上
313	TS规范	P1	(row.submission.status ?? null) as StudentProctoringStatus["submissionStatus"] 使用 as 断言	用类型守卫函数校验 status 值
378	TS规范	P1	row.event.eventType as ProctoringEventType 同上	同上
5-9	架构违规	P1	直接导入 exams、examSubmissions 表	通过 @/modules/exams/data-access 暴露的函数获取
188-193	性能	P2	getExamProctoringSummary 中对 submissions 数组调用两次 .filter()	用单次 for 循环同时统计两个计数
178-223	性能	P2	getExamProctoringSummary 中 submissions 查询、eventStats 查询、studentEventCounts 查询三者相互独立，却串行 await	用 Promise.all 并行执行

src/modules/proctoring/types.ts

未发现违规问题。

---

3.18 diagnostic（诊断模块）

src/modules/diagnostic/actions.ts

行号范围	问题类别	严重程度	问题描述	改进建议
26-33, 54-61, 82-85, 105-108	Server Action规范	P1	generateStudentReportAction、generateClassReportAction、publishReportAction、deleteReportAction 均使用手动 typeof + length 校验，未使用 Zod schema	新建 schema.ts，定义 Zod schema
121-133, 136-148	Server Action规范	P2	getDiagnosticReportsAction(params) 和 getDiagnosticReportByIdAction(id) 直接接收参数，未经 Zod 校验	对入参用 Zod 校验
123, 138	TS规范	P2	Promise<ActionState<Awaited<ReturnType<typeof getDiagnosticReports>>>> 类型表达式过于复杂	在 types.ts 中定义具名返回类型并导入

src/modules/diagnostic/data-access.ts

行号范围	问题类别	严重程度	问题描述	改进建议
9, 13	架构违规	P1	直接导入 examSubmissions、submissionAnswers、questionsToKnowledgePoints 表	通过对应模块的 data-access 函数获取数据
116	性能	P2	answers.find((a) => a.questionId === link.questionId) 在 for 循环内调用，O(n×m) 复杂度	先用 new Map(answers.map(a => [a.questionId, a])) 构建 Map
125-146	性能	P2	for 循环内逐条 await db.insert().onDuplicateKeyUpdate()，N 个知识点产生 N 次 DB 往返	用 Promise.all 并行化，或构建批量 upsert
80-81	性能	P2	allMastery.filter(m => m.masteryLevel >= 80) 和 allMastery.filter(m => m.masteryLevel < 60) 两次遍历同一数组	合并为单次循环
全文件	性能	P2	所有读函数均未用 React.cache() 包裹	用 cache() 包裹读函数

src/modules/diagnostic/data-access-reports.ts

行号范围	问题类别	严重程度	问题描述	改进建议
29-31	TS规范	P1	(r.strengths as string[] | null)、(r.weaknesses as string[] | null)、(r.recommendations as string[] | null) 三处 as 断言	编写类型守卫 isStringArray(v: unknown): v is string[]
59, 103	性能/规范	P2	const { createId } = await import("@paralleldrive/cuid2") 在函数内部动态导入	改为顶层静态导入
201-202	代码质量	P2	void round2 — 为抑制未使用警告而保留无用函数	直接删除 round2 函数定义及 void round2
172-180	性能	P2	getDiagnosticReportById 中先查 report，再单独查 generator 名称，两次串行查询	将 generator 查询合并到主查询的 JOIN 中
全文件	性能	P2	getDiagnosticReports、getDiagnosticReportById 未用 React.cache() 包裹	用 cache() 包裹
107	代码质量	P2	studentId: generatedBy 班级报告将生成者 ID 存入 studentId 字段	考虑将 studentId 改为可空，或使用单独的 classId 字段

src/modules/diagnostic/types.ts

未发现违规问题。

---

3.19 dashboard（仪表盘模块）

src/modules/dashboard/data-access.ts & types.ts

无违规问题。正确使用 Promise.all 并行获取多模块数据，正确使用 cache()，正确通过各模块 data-access 通信。是除 textbooks 外的另一个标杆模块。

---

3.20 files（文件模块）

src/modules/files/data-access.ts

行号范围	问题类别	严重程度	问题描述	改进建议
190	TS规范	P1	const conditions = [] 缺少类型标注，TypeScript 推断为 never[] 或 any[]	改为 const conditions: SQL[] = []
204	TS规范	P1	or(...)! 使用非空断言	显式处理 undefined
160-170	性能	P2	deleteFileAttachments 回退逻辑中 for 循环内逐条 await db.delete()	用 Promise.allSettled 并行删除
53-55, 70-72, 95-97, 114-116, 131-133, 143-145, 219-221, 248-250, 264-266	代码质量	P2	大量 catch { return null / [] / false } 静默吞掉异常，共 9 处	至少 console.error 记录错误信息
全文件	性能	P2	所有读函数均未用 React.cache() 包裹	用 cache() 包裹读函数

src/modules/files/types.ts

未发现违规问题。

---

3.21 announcements（公告模块）

src/modules/announcements/data-access.ts（186 行）

行号范围	问题类别	严重程度	问题描述	改进建议
46-47	TS规范	P1	toIso(row.createdAt) as string — as 断言掩盖潜在 null	让 toIso 对非空入参返回 string，拆分为两个函数
59, 62	TS规范	P2	params.status as AnnouncementStatus — 冗余 as 断言	直接使用收窄后的变量
88-90, 118-120	性能/可靠性	P2	catch {} 静默吞掉所有异常	至少记录错误日志
25-26	命名/DRY	P2	mapRow 参数中内联定义类型，与 types.ts 重复	导入并复用 types.ts 中的类型

src/modules/announcements/actions.ts（231 行）

行号范围	问题类别	严重程度	问题描述	改进建议
217-231	Server Action规范	P2	getAnnouncementsAction 使用 requireAuth() 而非 requirePermission(Permissions.ANNOUNCEMENT_READ)	改为 requirePermission(Permissions.ANNOUNCEMENT_READ)
73-79, 137-143, 159-165, 185-191, 208-214, 224-230	性能/可维护性	P2	6 个 Action 的 try/catch 错误处理块完全相同	提取共享错误处理函数 handleActionError(e)

src/modules/announcements/schema.ts（45 行）& types.ts（50 行）

符合规范。

---

3.22 settings（设置模块）

src/modules/settings/actions.ts（205 行）

行号范围	问题类别	严重程度	问题描述	改进建议
8, 64-76, 95-100, 104-113, 123-139, 154-169	架构违规	P1	模块无 data-access.ts 文件，actions.ts 直接 import { db } 并执行 DB 查询	新建 data-access.ts，将所有 DB 操作下沉
62-77	Server Action规范	P2	getAiProviderSummaries 返回 Promise<AiProviderSummary[]> 而非 ActionState<T>	移至 data-access.ts 或包装为 ActionState
38-46	架构违规	P2	AiProviderSummary 类型定义在 actions.ts 中	新建 types.ts，将类型移入
48-51	TS规范	P2	ensureUser 是 async 箭头函数，未显式标注返回类型	添加 : Promise<{ id: string }>
53-60	TS规范	P2	normalizeBaseUrl 未显式标注返回类型	添加 : string | null
95-113	性能	P2	upsertAiProviderAction 的更新分支中，count() 查询与 select 查询是两个独立查询，串行执行	用 Promise.all 并行化
120, 152	命名规范	P2	nextIsDefault、makeDefault 布尔变量前缀不规范	改为 isNextDefault、shouldMakeDefault

src/modules/settings/actions-password.ts（113 行）

行号范围	问题类别	严重程度	问题描述	改进建议
7, 58-62, 78-81, 83-87, 89-105	架构违规	P1	actions-password.ts 直接 import { db } 并执行 DB 操作，无 data-access.ts	将 DB 操作下沉至 data-access.ts
39-51	Server Action规范	P1	输入通过 String(formData.get(...)) 手动读取，未使用 Zod schema 验证	定义 Zod schema 并 safeParse
30	Server Action规范	P2	changePasswordAction 使用 requireAuth() 而非 requirePermission()	新增 PASSWORD_SELF_CHANGE 权限点并赋给所有角色
58-87	性能	P2	查询 user 和查询 passwordSecurity 是两个独立表的查询，当前串行执行	重构为 Promise.all 并行获取
14-18	TS规范	P2	normalizeBcryptHash 未显式标注返回类型	添加 : string

---

3.23 layout（布局模块）

src/modules/layout/config/navigation.ts（317 行）

行号范围	问题类别	严重程度	问题描述	改进建议
30-31	TS规范	P2	NavItem.permission 和子项的 permission 均为 string 类型，但项目已有 Permission 类型	导入 Permission 类型并使用
34	架构违规	P2	export type Role = "admin" | "teacher" | "student" | "parent" 定义在 config 文件中	考虑将 Role 类型提升至 @/shared/types

---

四、跨模块共性问题

4.1 架构违规（P0/P1，最高优先级）

4.1.1 跨模块直接查询 DB 表（最普遍问题）

调用方模块	被查模块表	严重程度
exams	questions（直写）、classes、subjects、grades	P0/P1
homework	exams（5 处）、classes、classEnrollments、subjects、users	P1
questions	knowledgePoints、chapters、textbooks	P1
grades	classes、classEnrollments、subjects、users	P1
classes	homeworkAssignments、homeworkSubmissions、exams、classSchedule	P0
school	（actions 层直接 DB 操作）	P0
scheduling	users（actions 层）	P0
messaging	classEnrollments、classes	P1
notifications	classes、classEnrollments、messaging（循环）	P0/P1
parent	users、grades、classEnrollments、classes	P1
proctoring	exams、examSubmissions	P0/P1
diagnostic	examSubmissions、submissionAnswers、questionsToKnowledgePoints	P1
elective	classes、classEnrollments	P1

统一修复方案：在各模块 data-access 暴露跨模块查询接口，消除直查。

4.1.2 messaging↔notifications 循环依赖

• messaging/data-access.ts 写 messageNotifications 表
• notifications/data-access.ts 反向 import messaging 的 notification-preferences 和 types
• notifications/channels/in-app-channel.ts 动态 import messaging 的 data-access

修复方案：将 messageNotifications 和 notificationPreferences 表所有权移交 notifications 模块。

4.1.3 actions 层直接操作 DB

模块	文件	问题
school	actions.ts	所有 mutation 直接操作 DB
scheduling	actions.ts	直接查询 users 表
proctoring	actions.ts	直接查询 examSubmissions 表
classes	actions.ts	直接查询 grades、classes 表做权限校验
settings	actions.ts、actions-password.ts	无 data-access.ts，直接 DB 操作
users	actions.ts	updateUserProfile 直接 db.update

统一修复方案：DB 操作必须下沉到 data-access.ts。

4.2 TypeScript 规范违规（P1）

4.2.1 as 断言滥用（非从 unknown 转换）

模块	文件	行号
exams	data-access.ts	76, 160, 361, 108, 172
exams	actions.ts	270, 349-351
homework	data-access.ts	39, 124, 226, 314, 392, 467, 645
homework	stats-service.ts	220
textbooks	actions.ts	54-58, 92-98, 154, 219-221, 259-261（14 处）
textbooks	data-access.ts	51
classes	data-access.ts	240, 266, 561
classes	data-access-admin.ts	135, 259, 349
classes	data-access-schedule.ts	54, 93
classes	data-access-stats.ts	250, 261, 512, 523
classes	actions.ts	538, 582
course-plans	data-access.ts	149
messaging	data-access.ts	80, 74, 85
notifications	channels/in-app-channel.ts	54（非法）
notifications	channels/sms-channel.ts	32
audit	data-access.ts	75, 122, 123, 186
elective	data-access.ts	117
elective	data-access-selections.ts	102, 114
proctoring	data-access.ts	127, 152, 208, 290, 313, 378
proctoring	actions.ts	39
diagnostic	data-access-reports.ts	29-31
parent	data-access.ts	30
announcements	data-access.ts	46-47, 59, 62
attendance	data-access.ts	195（Record<string, unknown>）

统一修复方案：用类型守卫函数或 Zod 校验替换 as 断言。

4.2.2 非空断言 !

模块	文件	行号
exams	ai-pipeline.ts	464, 657, 665, 666, 671
homework	export.ts	154
textbooks	data-access.ts	42, 71
classes	data-access.ts	287, 567
classes	data-access-admin.ts	369
classes	data-access-students.ts	102
scheduling	data-access.ts	140, 221, 222
scheduling	actions.ts	115
scheduling	auto-scheduler.ts	144, 145
messaging	data-access.ts	97, 117, 163
files	data-access.ts	204

统一修复方案：用显式判空处理替换非空断言。

4.2.3 函数返回值未显式标注

模块	文件	函数
classes	data-access.ts	isDuplicateInvitationCodeError, generateInvitationCode, normalizeSortText, parseFirstInt, compareGradeLabel, compareClassLike
classes	data-access-admin.ts	getManagedGrades
scheduling	data-access.ts	getAdminClassesForScheduling, getTeachersForScheduling, getClassroomsForScheduling, getClassSubjectsForScheduling
users	data-access.ts	normalizeRoleName, resolvePrimaryRole
users	user-service.ts	normalizeBcryptHash
messaging	data-access.ts	mapMessage, mapNotification
messaging	notification-preferences.ts	toIso, mapRow
notifications	dispatcher.ts	getSenders, selectChannels
notifications	channels/email-channel.ts	getEmailConfig, getTypeColor, buildHtmlContent, escapeHtml
notifications	channels/sms-channel.ts	getSmsConfig, buildTemplateParams
notifications	channels/wechat-channel.ts	getWechatConfig, buildTemplateData
audit	data-access.ts	toIso, clampPageSize, clampPage
parent	data-access.ts	getChildBasicInfo
announcements	—	—
settings	actions.ts	ensureUser, normalizeBaseUrl
settings	actions-password.ts	normalizeBcryptHash
elective	data-access.ts	buildCourseSelect
elective	data-access-selections.ts	buildCourseSelect, selectionDetailSelect
elective	schema.ts	emptyToNull, optionalStringToNull
questions	actions.ts	getQuestionsAction

统一修复方案：所有函数（特别是箭头函数）必须显式标注返回类型。

4.2.4 import type 未使用

模块	文件	行号
exams	actions.ts	4
questions	actions.ts	7
textbooks	actions.ts	18
proctoring	actions.ts	3

统一修复方案：仅用于类型的导入必须使用 import type。

4.3 Server Action 规范违规

4.3.1 requireAuth() 替代 requirePermission()

模块	文件	Action
users	actions.ts	updateUserProfile
messaging	actions.ts	getNotificationsAction, markNotificationAsReadAction, markAllNotificationsAsReadAction, getNotificationPreferencesAction, updateNotificationPreferencesAction
proctoring	actions.ts	recordProctoringEventAction
announcements	actions.ts	getAnnouncementsAction
settings	actions-password.ts	changePasswordAction

统一修复方案：改为 requirePermission(Permissions.XXX)。

4.3.2 缺少 Zod 验证

模块	文件	问题
textbooks	actions.ts	完全无 schema.ts，所有 Action 无 Zod 验证
classes	actions.ts	完全无 schema.ts，使用手动 typeof 检查
diagnostic	actions.ts	4 个 Action 使用手动 typeof 校验
settings	actions-password.ts	输入手动读取，无 Zod
messaging	actions.ts	多个 Action 参数未 Zod 校验
notifications	actions.ts	多个 Action 参数未 Zod 校验
audit	actions.ts	多个 Action 参数未 Zod 校验
users	actions.ts	updateUserProfile 无 Zod
elective	actions.ts	getStudentSelectionsAction 无 Zod

统一修复方案：新建/补充 schema.ts，所有 Action 输入用 Zod 验证。

4.3.3 缺少 revalidatePath

模块	文件	Action
course-plans	actions.ts	deleteCoursePlanItemAction, toggleCoursePlanItemCompletedAction
proctoring	actions.ts	recordProctoringEventAction

4.3.4 未返回 ActionState<T>

模块	文件	Action
questions	actions.ts	getQuestionsAction, getKnowledgePointOptionsAction
users	actions.ts	updateUserProfile（返回 Promise）
settings	actions.ts	getAiProviderSummaries（返回原始数组）

4.4 重复代码

重复内容	出现位置	修复方案
normalizeRoleName	users/data-access.ts、shared/lib/role-utils.ts	复用 shared
normalizeBcryptHash	users/user-service.ts、settings/actions-password.ts、shared/lib/bcrypt-utils.ts	复用 shared
toNumber/normalize/buildScopeClassFilter	grades/data-access.ts、data-access-analytics.ts、data-access-ranking.ts	提取到 grades/utils.ts
serializeDate	scheduling/data-access.ts、attendance/data-access.ts、attendance/data-access-stats.ts	提取到 shared
toIso	announcements/data-access.ts、messaging/data-access.ts、messaging/notification-preferences.ts、audit/data-access.ts	提取到 shared
try/catch 错误处理块	announcements/actions.ts（6 处）	提取 handleActionError(e)
Excel 导出逻辑	audit/actions.ts（3 处）	抽取 buildExcelSheet

4.5 错误吞没（静默 catch）

模块	文件	处数
school	data-access.ts	6
classes	data-access-admin.ts、data-access-students.ts	多处
course-plans	data-access.ts	2
announcements	data-access.ts	2
files	data-access.ts	9
audit	data-access.ts	3
elective	data-access.ts	2

统一修复方案：至少 console.error 记录错误，或向上抛出由调用方处理。

4.6 不可达代码

模块	文件	行号
classes	data-access.ts	297-299（throw 后 return id）
classes	data-access-admin.ts	380-382（throw 后 return id）
questions	actions.ts	158-163, 170-175（catch 块两分支都 throw e）

---

五、性能优化专项（react-best-practices）

依据 Vercel React Best Practices 规则集，识别以下性能优化机会：

5.1 CRITICAL：消除瀑布流（async-*）

5.1.1 async-parallel：独立操作用 Promise.all()

模块	文件	行号	问题	修复
classes	data-access.ts	120-127	getAccessibleClassIdsForTeacher 两个独立 DB 查询串行	Promise.all
settings	actions.ts	95-113	upsertAiProviderAction count 与 select 串行	Promise.all
settings	actions-password.ts	58-87	user 与 passwordSecurity 查询串行	Promise.all
elective	data-access-operations.ts	18-34	runLottery course 与 selections 串行	Promise.all
elective	data-access-operations.ts	86-112	selectCourse course 与 existing 串行	Promise.all
elective	data-access-operations.ts	158-182	dropCourse existing 与 course 串行	Promise.all
proctoring	data-access.ts	178-223	getExamProctoringSummary 三个独立查询串行	Promise.all
diagnostic	data-access-reports.ts	172-180	getDiagnosticReportById report 与 generator 串行	合并 JOIN 或 Promise.all
parent	data-access.ts	58-117	getChildBasicInfo 4 个串行查询	JOIN 或 Promise.all

5.1.2 async-defer-await：将 await 移到实际使用的分支

无明显违规，多数文件已正确处理。

5.2 HIGH：服务端性能（server-*）

5.2.1 server-cache-react：用 React.cache() 做请求内去重

模块	文件	缺失 cache() 的函数
grades	data-access.ts	getGradeRecords, getGradeRecordById, getClassGradeStats
grades	data-access-analytics.ts	getClassComparison, getGradeTrends
grades	data-access-ranking.ts	getClassRanking, getStudentRanking
elective	data-access-selections.ts	getCourseSelections, getStudentSelections, getStudentGradeId, getAvailableCoursesForStudent
diagnostic	data-access.ts	getStudentMastery, getStudentMasterySummary, getClassMasterySummary, getKnowledgePointStats
diagnostic	data-access-reports.ts	getDiagnosticReports, getDiagnosticReportById
files	data-access.ts	getFileAttachment, getFileAttachmentsByTarget, getFileAttachmentsByUploader, getAllFileAttachments, getFileAttachmentsWithFilters, getFileStats, getFileAttachmentsByIds
proctoring	data-access.ts	多个查询函数

标杆：exams、homework、questions、textbooks、dashboard、announcements 已正确使用 cache() ✓。

5.2.2 server-after-nonblocking：用 after() 做非阻塞操作

模块	文件	行号	问题
school	actions.ts	188, 219, 235	await logAudit(...) 阻塞响应

修复：使用 Next.js after() 将审计日志改为非阻塞。

5.2.3 server-serialization：最小化传给客户端组件的数据

需结合前端组件审查，本次后端核查未深入。

5.3 MEDIUM：JavaScript 性能（js-*）

5.3.1 js-set-map-lookups：用 Set/Map 做 O(1) 查找

模块	文件	行号	问题
grades	data-access-analytics.ts	133-136	scope.classIds.includes(c.id) — O(n) 查找
diagnostic	data-access.ts	116	answers.find(...) 在 for 循环内 — O(n×m)

修复：将数组转为 Set/Map 后用 .has() / .get()。

5.3.2 js-combine-iterations：合并多次 filter/map 为一次循环

模块	文件	行号	问题
grades	data-access.ts	248-252	两次 if 判断遍历同一数组
grades	data-access-analytics.ts	180-181, 238-239	两次 filter 遍历同一数组
grades	data-access-ranking.ts	100, 102	findIndex 和 find 查找同一元素
diagnostic	data-access.ts	80-81	两次 filter 遍历同一数组
proctoring	data-access.ts	188-193	两次 filter 统计 submissions

5.3.3 js-early-exit：函数早返回

多数文件已正确处理。

5.3.4 动态 import 改静态 import

模块	文件	行号	问题
grades	data-access.ts	148, 172	await import("@paralleldrive/cuid2") 函数内动态导入
diagnostic	data-access-reports.ts	59, 103	同上

修复：改为文件顶部静态 import { createId } from "@paralleldrive/cuid2"。

5.4 性能问题汇总（按影响排序）

优先级	问题	影响范围
CRITICAL	grades N+1 查询（getClassComparison）	大班级成绩对比性能差
HIGH	循环内串行 await db.update/insert（homework/data-access-write.ts、elective/data-access-operations.ts、diagnostic/data-access.ts、course-plans/data-access.ts）	批量操作慢
HIGH	大量读函数未用 React.cache()（grades、elective、diagnostic、files、proctoring）	请求内重复查询
MEDIUM	独立查询未并行化（9 处）	响应时间累加
MEDIUM	动态 import（3 处）	每次调用有开销
LOW	重复 filter 遍历（5 处）	微小性能损失
LOW	O(n) 查找代替 O(1)（2 处）	微小性能损失

---

六、优先修复路线图

第一阶段：P0 严重问题（立即修复）

1. exams/data-access.ts：persistAiGeneratedExamDraft 改为调用 questions data-access
2. exams/data-access.ts：getExams/getExamById 改为通过 classes data-access 获取 gradeId
3. questions/schema.ts：z.any() → z.unknown()
4. questions/actions.ts：getQuestionsAction 和 getKnowledgePointOptionsAction 包装为 ActionState
5. textbooks/actions.ts：新建 schema.ts，添加 Zod 验证；清理 14 处 as 断言
6. grades/data-access-analytics.ts：getClassComparison N+1 查询重构为 inArray 批量查询
7. classes/data-access-stats.ts、data-access-students.ts：移除对 homework/exams 表的直接查询
8. school/actions.ts：所有 DB 操作下沉到 data-access.ts
9. proctoring/actions.ts：DB 查询下沉到 data-access.ts
10. messaging↔notifications：将 messageNotifications 和 notificationPreferences 表所有权移交 notifications 模块
11. notifications/channels/in-app-channel.ts:54：修复非法 as 断言
12. users/user-service.ts:13：移除硬编码弱密码 "123456"
13. users/actions.ts：updateUserProfile 整改（权限+下沉+返回类型）
14. scheduling/data-access.ts：4 个函数补充返回类型标注

第二阶段：P1 重要问题（尽快修复）

1. 跨模块直查 DB：在各模块 data-access 暴露跨模块查询接口，消除直查（涉及 exams、homework、questions、grades、classes、messaging、notifications、parent、proctoring、diagnostic、elective）
2. as 断言清理：全局替换为类型守卫（涉及 20+ 文件，60+ 处）
3. requireAuth → requirePermission：users、messaging、proctoring、announcements、settings 共 8 处
4. import type 修正：exams、questions、textbooks、proctoring 共 4 处
5. 动态 import 改静态：grades、diagnostic 共 3 处
6. grades/data-access.ts:249：除零 bug 守卫
7. audit/data-access.ts：导出函数数据截断问题（3 处）
8. elective/data-access-operations.ts：runLottery 加事务包裹 + 批量更新
9. diagnostic/actions.ts：新建 schema.ts，用 Zod 替代手动校验
10. classes 模块：新建 schema.ts，用 Zod 替换 actions.ts 中的手动校验
11. course-plans/actions.ts：补齐 revalidatePath 调用（2 处）
12. homework/data-access-write.ts:305-311：gradeHomeworkAnswers 加事务包裹
13. users/user-service.ts：batchImportUsers 加事务包裹
14. 不可达代码清理：classes/data-access.ts:297-299、classes/data-access-admin.ts:380-382

第三阶段：P2 优化（迭代修复）

1. React.cache() 包装：grades、elective、diagnostic、files、proctoring 读函数添加 cache()
2. Promise.all 并行化：9 处独立查询串行执行
3. after() 非阻塞审计日志：school/actions.ts（3 处）
4. 错误吞没清理：school、classes、course-plans、announcements、files、audit、elective 共 30+ 处静默 catch
5. 非空断言 ! 清理：20+ 处替换为显式判空
6. 函数返回类型补齐：30+ 个箭头函数
7. 重复代码提取：normalizeRoleName、normalizeBcryptHash、toIso、serializeDate、toNumber/normalize、handleActionError、buildExcelSheet
8. 合并 filter 遍历：5 处
9. Set/Map 查找优化：2 处
10. 架构文档同步：exams/actions.ts 行数、settings 导出函数列表、P2-11 状态、announcements 依赖关系
11. exams/ai-pipeline.ts 拆分：912 行按职责拆分为 4 个文件
12. layout/navigation.ts：permission 字段改用 Permission 类型
13. notifications/external-sdk.d.ts：安装实际 SDK 后用其自带类型覆盖 any

---

附录：核查方法说明

核查流程

1. 架构图优先：先阅读 docs/architecture/004_architecture_impact_map.md，理解模块依赖关系和已知问题
2. 并行核查：启动 5 个并行搜索代理，分别核查核心教学、教学管理、用户沟通、扩展功能、其他模块
3. 逐文件审查：每个代理读取所有后端 .ts 文件，对照项目规范逐条核查
4. 性能规则应用：应用 Vercel React Best Practices 的 65 条规则，识别性能优化机会
5. 结果汇总：合并 5 个代理的核查结果，按严重程度和模块分类整理

核查依据

• .trae/rules/project_rules.md：项目规则（架构分层、TS规范、命名、组件、Server Action、Tailwind、安全、提交）
• docs/standards/coding-standards.md：编码规范（详细规范）
• docs/architecture/004_architecture_impact_map.md：架构影响地图（模块清单、依赖关系、已知问题）
• docs/architecture/005_architecture_data.json：AI 友好格式的结构化数据
• Vercel React Best Practices：65 条性能优化规则（8 个类别）

未核查范围

• src/modules/*/components/ 下的前端组件文件
• src/modules/*/hooks/ 下的 Hook 文件
• src/shared/ 下的基础设施文件
• src/app/ 下的路由层文件
• 测试文件（*.test.ts）

如需核查上述范围，请另行指派任务。