NextEdu/docs/architecture/audit/00_summary.md

架构审查汇总报告

基于对全项目 69+ 文件的逐文件审查,汇总关键架构问题。 审查日期: 2026-06-17 子报告:

• shared 基础设施层审查
• 核心业务模块审查
• 管理模块群审查
• 新增模块和其他模块审查

---

一、总体评估

维度	状态	说明
模块化程度	⚠️ 中等	20+ 模块划分合理,但跨模块直接 DB 查询普遍存在
职责单一性	✅ 良好	多数模块职责清晰,文件超 1000 行问题已修复（仅 schema.ts 保留）
架构文档质量	❌ 不足	004 文档按模块罗列函数,缺乏关系图/数据流/调用链
循环依赖	✅ 已修复	shared/lib ↔ auth 循环依赖通过动态 import 打破
死代码	⚠️ 用户保留	proctoring/exam-mode-config.tsx 未集成（用户决定保留）

核心结论: 架构设计思路正确(模块化 + 分层),但执行不够严格。主要问题是跨模块直接 DB 查询破坏了模块封装,以及少数文件过大。

---

二、P0 严重问题(必须修复)

1. 文件超 1000 行硬上限 ✅ 已修复

文件	行数	问题
classes/data-access.ts	2104 → 548	混入 homework/scheduling/grades 逻辑 ✅ 已拆分为 5 个文件
homework/data-access.ts	1038 → 598	混入排名计算业务逻辑 ✅ 已拆分（新增 stats-service.ts + data-access-write.ts）
shared/db/schema.ts	1111	54 张表混合（P2-1 待拆分）

2. 循环依赖 ✅ 已修复

shared/lib/{audit-logger, change-logger, auth-guard} → @/auth (src/auth.ts) → shared/lib/* (循环)

已完成修复（2026-06-17）：3 个 logger/guard 文件改用动态 import("@/auth") 打破模块级静态循环依赖。

3. dashboard 跨模块直接查询 11 张表 ✅ 已修复

dashboard/data-access.ts 的 getAdminDashboardData 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装。

已完成修复（2026-06-17）：dashboard/data-access.ts 改为并行调用各模块的 get[Module]DashboardStats() 函数（42 行），不再直接查询任何业务表。

4. messaging 绕过 notifications 直接写通知 ✅ 已修复

messaging/actions.ts 第 66-72 行直接调用 createNotification,导致用户通知偏好失效、多渠道通知无效。

已完成修复（2026-06-17）：messaging/actions.ts 改用 sendNotification from @/modules/notifications/dispatcher，尊重用户通知偏好。

5. classSchedule 表三处写入口 ✅ 已修复

- classes/data-access.ts - scheduling/actions.ts (直接 transaction 写入) - scheduling/data-access.ts

已完成修复（2026-06-17）：scheduling/data-access.ts 新增 replaceClassSchedule() 统一写入口，scheduling/actions.ts 改为调用该函数，不再直接 transaction 写入。

---

三、P1 较严重问题

6. 跨模块直接 DB 查询普遍存在

被访问表	访问次数	应归属模块	主要违规者
classes	8+	classes	exams, homework, grades, dashboard
classEnrollments	6+	classes	homework, grades, attendance
users	6+	users	多个模块
subjects	6+	school	exams, homework, questions
exams	5+	exams	homework, grades, dashboard

7. actions 层混入数据访问逻辑 ✅ 已修复

exams/homework/questions/announcements 的 actions.ts 中存在直接 db.insert/update/delete,应该通过 data-access 层。

已完成修复（2026-06-17，commit 84d6636）：4 个模块的 actions 层 DB 操作全部下沉到 data-access：

• exams：新增 7 个 data-access 函数，actions.ts 832→691 行，data-access.ts 339→471 行
• homework：新建 data-access-write.ts（285 行，10 个写函数），actions.ts 387→239 行
• questions：新增 4 个 data-access 函数，actions.ts 294→149 行，data-access.ts 129→260 行
• announcements：新增 5 个 data-access 函数，actions.ts 242→197 行，data-access.ts 120→171 行

剩余未修复：users（updateUserProfileAction）、scheduling（applyAutoScheduleAction/autoScheduleAction）

8. auth.ts 混合 5 类职责 ✅ 已修复

NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数,应拆分。

已完成修复（2026-06-17）：auth.ts 拆分出 4 个 shared/lib 文件：

• password-security-service.ts（84 行）- 密码安全 DB 操作
• role-utils.ts（31 行）- 角色规范化
• bcrypt-utils.ts（18 行）- bcrypt 哈希规范化
• http-utils.ts（27 行）- IP 解析

auth.ts 从 293 行降至 193 行，仅保留 NextAuth 配置。

9. users/import-export.ts 四重职责 ✅ 已修复

导入解析 + 导出 + 用户创建(含密码哈希) + 班级注册(跨模块写 classEnrollments)。

已完成修复（2026-06-17）：拆分为 3 个文件：

• import-export.ts（157 行）- 仅文件解析与生成
• user-service.ts（82 行）- 用户创建（含密码哈希）
• class-registration.ts（21 行）- 班级注册（调用 classes/data-access）

10. proctoring 死代码 ⚠️ 用户决定保留

exam-mode-config.tsx 组件已创建但未集成到考试表单,DB schema 有 examMode 字段但表单不收集。

状态：用户决定保留该组件，暂不集成也不删除。

---

四、架构文档问题

当前 004 文档的问题

1. 按模块罗列函数签名,缺乏全局视角
2. 缺少模块依赖关系图,无法直观看出模块间如何协作
3. 缺少数据流向图,不知道数据如何在模块间流动
4. 缺少调用链路,不知道一个请求从 API 到 DB 的完整路径
5. 缺少分层架构说明,不知道 shared/modules/app 的层次关系
6. 未标注循环依赖,给人虚假的"架构清晰"印象

理想的架构文档应该

1. 一图胜千言: 用 ASCII/Mermaid 图展示模块关系
2. 分层清晰: shared → modules → app 三层,依赖方向单向
3. 数据流明确: 标注每个核心业务的数据从哪来、到哪去
4. 调用链完整: 关键 API 的完整调用路径
5. 问题标注: 明确标注已知的耦合问题和技术债

---

五、解耦优先级

立即执行(P0)

1. 拆分 classes/data-access.ts(2104 行 → 按职责拆 3-4 个文件) ✅ 已完成（拆为 5 个文件，均 ≤800 行）
2. 拆分 homework/data-access.ts(1038 行 → 分离排名逻辑) ✅ 已完成（新增 stats-service.ts + data-access-write.ts）
3. 修复 shared/lib ↔ auth 循环依赖 ✅ 已完成（动态 import）
4. dashboard 改为通过各模块 data-access 获取数据 ✅ 已完成（42 行，调用各模块 stats 函数）
5. messaging 写通知改为通过 notifications dispatcher ✅ 已完成（改用 sendNotification）

短期执行(P1)

6. 统一 classSchedule 写入口到 scheduling 模块 ✅ 已完成（replaceClassSchedule 统一入口）
7. actions 层移除直接 DB 操作 ✅ 部分完成（exams/homework/questions/announcements 已修复，users/scheduling 待处理）
8. 拆分 auth.ts ✅ 已完成（拆分出 4 个 shared/lib 文件，auth.ts 降至 193 行）
9. 集成 proctoring/exam-mode-config 到考试表单 ⚠️ 用户决定保留，暂不处理
10. 拆分 users/import-export.ts ✅ 已完成（拆分为 import-export.ts + user-service.ts + class-registration.ts）

中期执行(P2)

11. 建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
12. schema.ts 按业务域分节(加注释分隔)
13. 拆分 shared/lib/ai.ts ✅ 已完成（P2-2，commit 6588f74，拆分为 ai/ 目录 6 个文件，原 ai.ts 保留为重导出）