Files

SpecialX 49291fcc31 refactor: fix all P0/P1/P2 bugs and architecture issues

Bug fixes (from bugs/ directory):

- Fix cross-module DB queries in 9 modules (homework, grades, parent, diagnostic, elective, proctoring, notifications, scheduling, classes) by routing through data-access functions

- Fix shared/lib <-> auth circular dependency via new session.ts module

- Fix divide-by-zero guard in grades data-access

- Fix audit export data truncation (paginated fetch for full datasets)

- Fix missing transactions in homework grading and elective lottery

- Fix missing revalidatePath in course-plans actions

- Fix frontend permission checks using requirePermission instead of requireAuth

- Fix dashboard role routing using session.user.roles

- Fix student auth pattern (migrate getDemoStudentUser to users module)

- Fix ActionState return type handling in components

Code quality fixes:

- Remove 60+ as type assertions (replace with type guards)

- Remove non-null assertions (use optional chaining or explicit checks)

- Convert dynamic imports to static imports (grades, diagnostic)

- Add React.cache() wrapping for read functions

- Parallelize independent queries with Promise.all

- Add explicit return types to 30+ arrow functions

- Replace any with unknown + type guards

- Fix import type for type-only imports

- Add Zod validation schemas for classes and diagnostic modules

- Extract duplicate code (normalizeRoleName, normalizeBcryptHash, logger IP extraction)

- Add console.error to silent catch blocks

- Fix permission naming consistency (exam:proctor_read -> exam:proctor:read)

Architecture doc sync:

- Update 004_architecture_impact_map.md and 005_architecture_data.json

- Update management-modules-audit.md for P0-7 cross-module fix

Moved deleted proctoring event route to deletes/ folder.

2026-06-19 05:13:34 +08:00

24 KiB

Raw Blame History

管理类模块职责与耦合审查报告

审查范围：school / classes / scheduling / attendance / users / audit / course-plans / announcements 审查日期：2026-06-17 审查依据：单一职责原则（SRP）、模块边界清晰度、跨模块耦合度、企业级代码规范（单文件 ≤ 1000 行硬性上限）审查方式：只读源码分析，未修改任何代码

一、总体评价

模块	行数（最大文件）	职责单一性	耦合度	严重度
school	325	✅ 良好	✅ 低	🟢 合格
classes	~~2104~~ → 548	✅ 已修复	❌ 严重	🟡 需改进
scheduling	335（data-access）/ 266（actions）	✅ 算法独立	⚠️ 中	🟡 需改进
attendance	271	✅ 良好	⚠️ 中	🟢 合格
users	157（import-export）	✅ 已修复	⚠️ 中	🟢 合格
audit	212	⚠️ 部分违反	✅ 低	🟡 需改进
course-plans	320	✅ 良好	✅ 低	🟢 合格
announcements	197	✅ 已修复	✅ 低	🟢 合格

核心结论：

~~classes 模块是全项目耦合最严重的模块，单文件 2104 行远超 1000 行硬性上限，混入了 schedule、homework、grades 三个业务领域的逻辑。~~ ✅ 已修复（2026-06-17 拆分为 5 个文件，均 ≤800 行）
~~users/import-export.ts 违反单一职责，同时处理导入、导出、用户创建、班级注册四类逻辑。~~ ✅ 已修复（2026-06-17 拆分为 import-export.ts + user-service.ts + class-registration.ts）
scheduling/auto-scheduler.ts 是算法独立化的优秀范例，纯函数、无 DB 访问、可独立测试。
~~announcements 和 audit 模块的 data-access 层不完整，写操作或导出逻辑泄漏到 actions 层。~~ announcements ✅ 已修复（写操作下沉 data-access）；audit 仍有导出逻辑内联。

二、模块审查明细

2.1 school 模块 — 🟢 合格

文件清单：actions.ts (325 行) / data-access.ts (186 行) / schema.ts (51 行) / types.ts (42 行)

职责边界：✅ 清晰。仅负责 schools / academicYears / departments / grades 的 CRUD。

优点：

actions.ts 每个 Action 职责单一：权限校验 → 解析 → DB 写入 → 审计日志 → revalidatePath。
data-access.ts 仅包含只读查询，无跨模块写入。
权限校验完整：SCHOOL_MANAGE / GRADE_MANAGE 均接入 requirePermission。

问题：

⚠️ 审计日志不一致：仅 school 实体的 create/update/delete 调用了 logAudit，而 department / academicYear / grade 的 CRUD 均未记录审计日志。
⚠️ getStaffOptions / getGrades 直接查询 users / roles / usersToRoles 表（跨模块读），但属于展示用关联查询，可接受。

建议：为 department / academicYear / grade 的 CRUD 补充 logAudit 调用，保持审计一致性。

2.2 classes 模块 — 🟡 需改进（文件拆分已修复，跨模块耦合部分已修复）

文件清单：actions.ts (676 行) / data-access.ts (548 行) / data-access-stats.ts (513 行) / data-access-schedule.ts (194 行) / data-access-students.ts (253 行) / data-access-admin.ts (406 行) / types.ts (201 行)

✅ data-access.ts 已于 2026-06-17 拆分为 5 个文件，所有文件均 ≤800 行，通过 re-export 保持向后兼容。 ✅ P0-7 已于 2026-06-18 修复：data-access-stats.ts 和 data-access-students.ts 不再直查 homework/exams 表，改为调用 homework/data-access-classes.ts 暴露的函数。

2.2.1 职责混乱 — 混入三个外部业务领域（拆分后仍存在于子文件中）

data-access-*.ts 文件群仍承载了四个业务领域的逻辑（已按职责分文件，homework 跨域查询已通过 data-access-classes 封装）：

文件	逻辑	应属模块
data-access.ts	教师身份解析、班级访问控制、班级 CRUD	classes（合理）
data-access-students.ts	班级学生查询	classes（合理）
data-access-stats.ts	`getClassHomeworkInsights` / `getGradeHomeworkInsights` 班级/年级作业洞察	classes（✅ P0-7 已修复：通过 `homework/data-access-classes` 获取数据）
data-access-schedule.ts	课表查询 `getClassSchedule`、课表项 CRUD	scheduling
data-access-admin.ts	`getStudentsSubjectScores` 学生科目成绩	classes（✅ P0-7 已修复：通过 `homework/data-access-classes` 获取数据）

关键问题（P1-1 部分已修复）：

✅ P0-7 已修复：getClassHomeworkInsights 和 getGradeHomeworkInsights 不再直接查询 homeworkAssignments、homeworkSubmissions、homeworkAssignmentTargets、homeworkAssignmentQuestions、exams 表，改为调用 homework/data-access-classes.ts 暴露的函数（getAssignmentIdsForStudents/getHomeworkAssignmentsWithSubject/getHomeworkAssignmentsByIds/getAssignmentMaxScoreById/getAssignmentTargetCounts/getHomeworkSubmissionsForStudents）。
✅ P0-7 已修复：getStudentsSubjectScores 不再直接关联 homeworkSubmissions + exams + subjects，改为调用 homework/data-access-classes.ts 暴露的函数（getAssignmentIdsForStudents/getPublishedHomeworkAssignmentsWithSubject/getHomeworkSubmissionsForAssignments）。
课表 CRUD（createClassScheduleItem / updateClassScheduleItem / deleteClassScheduleItem）写入 classSchedule 表，P0-6 已统一 scheduling/data-access 为写入口，但 classes 侧的写函数仍存在（待后续迁移）。

2.2.2 types.ts 跨领域类型污染

types.ts 定义了本应属于其他模块的类型：

ClassHomeworkInsights / GradeHomeworkInsights / ClassHomeworkAssignmentStats / ScoreStats / AssignmentSummary — 应属 homework 模块
ClassScheduleItem / CreateClassScheduleItemInput / UpdateClassScheduleItemInput / StudentScheduleItem — 与 scheduling 模块的 types.ts 存在概念重叠

2.2.3 actions.ts 跨模块直接查询

actions.ts 多处直接查询 grades 表（属于 school 模块）进行权限验证，绕过了 school/data-access：

行号	函数	直接查询
60-68	`createTeacherClassAction`	`db.select().from(grades)` 校验 gradeHead 权限
186-194	`createGradeClassAction`	`db.select().from(grades)` 校验年级管理权
241-249	`updateGradeClassAction`	`db.select().from(classes)` 绕过自身 data-access
251-272	`updateGradeClassAction`	`db.select().from(grades)` 校验源/目标年级
340-348	`deleteGradeClassAction`	`db.select().from(grades)` 校验权限

问题：权限校验逻辑散落在 actions 层，既未下沉到 data-access，也未通过 school 模块暴露的查询接口。

2.2.4 actions.ts 职责重复

存在三组近乎重复的 Action 集合：

Teacher 系列：createTeacherClassAction / updateTeacherClassAction / deleteTeacherClassAction
Admin 系列：createAdminClassAction / updateAdminClassAction / deleteAdminClassAction
Grade 系列：createGradeClassAction / updateGradeClassAction / deleteGradeClassAction

三者表单解析、字段校验逻辑高度重复，仅权限上下文不同。

2.2.5 data-access.ts 内调用 auth()

getSessionTeacherId（行 49-62）在 data-access 层直接调用 auth() 获取会话，违反"data-access 不感知请求上下文"的分层原则。会话信息应由 actions 层传入。

2.2.6 组件层边界模糊

classes/components/ 包含 schedule-view.tsx、schedule-filters.tsx、class-detail/class-schedule-widget.tsx 等课表相关组件，与 scheduling/components/ 的职责重叠。

整改建议（优先级 P0）：

将 getClassHomeworkInsights / getGradeHomeworkInsights / getStudentsSubjectScores / getClassStudentSubjectScoresV2 迁移至 homework / grades 模块。
将课表 CRUD（createClassScheduleItem 等）迁移至 scheduling 模块，统一 classSchedule 表的写入口。
将 data-access.ts 拆分为 data-access.ts（班级 CRUD）+ data-access-enrollments.ts（注册/邀请码）+ data-access-insights.ts（如暂不迁移则隔离）。
将权限校验中的 grades 表查询改为调用 school/data-access 暴露的接口。
将 getSessionTeacherId 上移至 actions 层或 shared/lib。

2.3 scheduling 模块 — 🟡 需改进（算法层优秀，写入口已统一）

文件清单：actions.ts (266 行) / auto-scheduler.ts (310 行) / data-access.ts (335 行) / schema.ts / types.ts

2.3.1 auto-scheduler.ts — ✅ 优秀范例

这是全项目算法独立化的最佳实践：

纯函数：findOptimalSlot / validateSchedule / autoSchedule / buildDefaultTimeSlots
无 "server-only" 副作用，无 DB 访问，无 import { db }
仅依赖 types.ts 的类型导入
可独立单元测试：给定输入即可断言输出，无需 mock 数据库
算法清晰：贪心 + 约束检查（午餐、每日上限、教师/教室冲突、避免连排）

建议：以此为模板，指导其他模块的算法抽取（如 homework 的批改评分算法、grades 的统计算法）。

2.3.2 actions.ts — 跨模块直接查询（写入口已统一）

行号	函数	问题
110-116	`autoScheduleAction`	直接 `db.select().from(users)` 查询教师，绕过 data-access 的 `getTeachersForScheduling`（P1-2 待修复）
~~168-180~~	~~`applyAutoScheduleAction`~~	~~直接 `db.transaction` 写入 `classSchedule` 表~~ ✅ 已修复（P0-6，改为调用 `replaceClassSchedule`）

applyAutoScheduleAction 的直接 transaction 写入问题已于 P0-6 修复，现在通过 scheduling/data-access.ts 的 replaceClassSchedule() 统一写入。但 autoScheduleAction 仍直接查询 users 表（P1-2 待修复）。

2.3.3 data-access.ts — 跨模块读查询 + 统一写入口

包含 getAdminClassesForScheduling / getTeachersForScheduling / getClassroomsForScheduling / getClassSubjectsForScheduling 四个辅助查询，直接访问 classes / classSubjectTeachers / subjects / users / classrooms 表。

P0-6 后新增 replaceClassSchedule() 作为 classSchedule 表的统一写入口。

这些是排课场景的只读辅助查询，耦合度可接受，但理想情况下应通过各所属模块的 data-access 暴露接口。

2.3.4 actions.ts 末尾 re-export

export { getSchedulingRules, getScheduleChanges, ... } from "./data-access"

actions 层 re-export data-access 函数是反模式，应让消费方直接从 data-access 导入。（P2 待修复）

整改建议：

~~将 applyAutoScheduleAction 中的 classSchedule 写入逻辑下沉到 data-access~~ ✅ 已完成（P0-6）
将 autoScheduleAction 中的 users 查询改用 getTeachersForScheduling（P1-2 待修复）
移除 actions.ts 末尾的 re-export（P2 待修复）

2.4 attendance 模块 — 🟢 合格（结构典范）

文件清单：actions.ts (271 行) / data-access.ts (271 行) / data-access-stats.ts (145 行) / schema.ts / types.ts

优点：

stats 独立拆分：data-access-stats.ts 专门承载统计逻辑，是 classes 模块应学习的拆分模式。
actions.ts 每个 Action 职责单一：权限校验 → 解析 → 委托 data-access → revalidate。
DataScope 数据范围控制完整接入，支持 6 种 scope 类型。
无写操作泄漏到 actions 层。

问题：

⚠️ getClassStudentsForAttendance（data-access.ts 行 206-217）直接查询 classEnrollments 表获取班级学生列表，属于 classes 模块数据，应通过 classes/data-access 暴露的接口调用。
⚠️ data-access.ts 和 data-access-stats.ts 均直接 JOIN classes 表获取班级名称（只读展示，可接受）。

整改建议：在 classes/data-access 暴露 getClassStudentIds(classId) 接口，供 attendance 调用。

2.5 users 模块 — 🟢 合格（已修复）

文件清单：actions.ts (131 行) / data-access.ts (133 行) / import-export.ts (157 行) / user-service.ts (82 行) / class-registration.ts (21 行)

✅ import-export.ts 已于 2026-06-17 拆分为 3 个文件，四重职责已分离。

2.5.1 import-export.ts — 四重职责已修复 ✅

原文件同时承载四类互不相关的职责，现已拆分：

文件	职责	行数
`import-export.ts`	文件解析与生成（`generateUserImportTemplate` / `parseUserImportData` / `exportUsersToExcel`）	157
`user-service.ts`	用户创建（含密码哈希 + 角色绑定）	82
`class-registration.ts`	班级注册（调用 classes/data-access）	21

已修复问题：

✅ 导入与导出未分离 → import-export.ts 仅负责文件解析与生成
✅ 用户创建逻辑泄漏 → 迁移至 user-service.ts
✅ 跨模块写 classEnrollments → 迁移至 class-registration.ts，调用 classes/data-access
✅ 跨模块读 classes → 通过 classes/data-access 暴露接口调用

2.5.2 actions.ts — 绕过 data-access（部分修复）

updateUserProfile（行 29-51）仍直接 db.update(users) 写入数据库，绕过了 data-access 层。（P1-2 待修复）

2.5.3 data-access.ts — 已扩展

从 71 行扩展到 133 行，包含 getUserProfile 及 dashboard 聚合查询函数 getUsersDashboardStats。用户创建、更新等写操作部分仍在 user-service.ts 中（P1-2 待进一步下沉）。

整改建议（优先级 P1）：

~~将 import-export.ts 拆分为 import.ts 与 export.ts~~ ✅ 已完成（采用按职责拆分）
~~将 batchImportUsers 中的用户创建逻辑迁移至 user-service.ts~~ ✅ 已完成
~~将 classEnrollments 写入改为调用 classes/data-access~~ ✅ 已完成
将 updateUserProfile 的 DB 写入下沉到 data-access（P1-2 待修复）

2.6 audit 模块 — 🟡 需改进

文件清单：actions.ts (212 行) / data-access.ts (260 行) / types.ts

问题：

⚠️ Excel 导出逻辑内联在 actions 层：exportAuditLogsAction / exportLoginLogsAction / exportDataChangeLogsAction 三个 Action 各自内联了 exportToExcel 调用及完整的列定义（表头、宽度、字段映射），每个约 40 行。这是展示/格式化逻辑，应抽取到独立的 export.ts。
⚠️ 三个导出 Action 的结构高度重复（权限校验 → 查询 → 构造 columns → exportToExcel → 返回 buffer），可抽象为通用导出工厂。

优点：

data-access.ts 职责清晰，仅包含日志查询，无跨模块问题。
分页逻辑统一（clampPage / clampPageSize）。

整改建议：抽取 export.ts，封装 exportAuditLogsToExcel(items) / exportLoginLogsToExcel(items) / exportDataChangeLogsToExcel(items)，actions 层仅负责编排。

2.7 course-plans 模块 — 🟢 合格

文件清单：actions.ts (265 行) / data-access.ts (320 行) / schema.ts / types.ts

优点：

actions.ts 使用 handleError / revalidatePlanPaths 辅助函数消除重复，是 actions 层的良好范例。
data-access.ts 职责清晰：课程计划 CRUD + 周计划项 CRUD + 排序。
跨模块查询仅为 classes / subjects / users 的 LEFT JOIN 取展示名称（只读，可接受）。

小问题：

⚠️ getSubjectOptions（行 310-320）直接查询 subjects 表，subjects 无独立模块，暂可接受。

结论：该模块结构可作为其他模块的参考模板。

2.8 announcements 模块 — 🟢 合格（已修复）

文件清单：actions.ts (197 行) / data-access.ts (171 行) / schema.ts / types.ts

✅ 写操作已下沉到 data-access 层（2026-06-17，commit 84d6636）。

核心问题 — 写操作泄漏到 actions 层 ✅ 已修复

~~data-access.ts 仅包含两个只读函数（getAnnouncements / getAnnouncementById），所有写操作均直接在 actions.ts 中执行 db.insert / db.update / db.delete~~

已完成修复：data-access.ts 从 120 行扩展到 171 行，新增 5 个写函数：

createAnnouncement
updateAnnouncement
deleteAnnouncement
publishAnnouncement
archiveAnnouncement

actions.ts 从 242 行降至 197 行，仅保留权限校验 + 解析 + 委托调用。

其他问题：

⚠️ 死代码：updateAnnouncementAction 行 108 计算 wasPublished，行 135 void wasPublished 显式丢弃，未实际使用。（P2 待清理）
⚠️ getAnnouncementsAction 使用 requireAuth() 而非 requirePermission(ANNOUNCEMENT_READ)，与其他模块的权限模式不一致。（P2 待统一）