Files

SpecialX f8dfd1dddd docs: 全项目架构审查与文档体系重写

- 全项目逐文件审查: 4 份审计报告(shared/core-business/management/new-modules)
- 重写 004 架构影响地图: 图优先 + 模块依赖图 + 数据流 + 调用链 + 问题分级
- 更新 005 结构化数据: 新增 architectureOverview/moduleDependencyGraph/knownIssues/dbTables 节点
- 更新 006 功能清单: 143 项功能标注实现状态, P0 覆盖率 80%->92%
- 更新 007 差距审计: v2->v3, P0 完成 69%->84%, 新增架构技术债章节
- 更新 001 项目概览: 6 角色/54 权限/26 模块/54 表
- 新增 docs/README.md 文档索引
- 归档 11 份过时文档(002x2/003/designx8) 标注
- 更新 work_log

2026-06-17 21:51:32 +08:00

4.8 KiB

Raw Blame History

架构审查汇总报告

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

shared 基础设施层审查

核心业务模块审查

管理模块群审查

新增模块和其他模块审查

一、总体评估

维度	状态	说明
模块化程度	⚠️ 中等	20+ 模块划分合理,但跨模块直接 DB 查询普遍存在
职责单一性	⚠️ 中等	多数模块职责清晰,但 5 个文件超 1000 行硬上限
架构文档质量	❌ 不足	004 文档按模块罗列函数,缺乏关系图/数据流/调用链
循环依赖	❌ 存在	shared/lib ↔ auth 循环依赖
死代码	⚠️ 少量	proctoring/exam-mode-config.tsx 未集成

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

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

1. 文件超 1000 行硬上限(3 个文件)

文件	行数	问题
`classes/data-access.ts`	2104	混入 homework/scheduling/grades 逻辑
`homework/data-access.ts`	1038	混入排名计算业务逻辑
`shared/db/schema.ts`	1111	54 张表混合(可接受,但需分节)

2. 循环依赖

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

3. dashboard 跨模块直接查询 11 张表

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

4. messaging 绕过 notifications 直接写通知

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

5. classSchedule 表三处写入口

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

数据完整性高风险。

三、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 层。

8. auth.ts 混合 5 类职责

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

9. users/import-export.ts 四重职责

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

10. proctoring 死代码

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

四、架构文档问题

当前 004 文档的问题

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

理想的架构文档应该

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

五、解耦优先级

立即执行(P0)

拆分 classes/data-access.ts(2104 行 → 按职责拆 3-4 个文件)
拆分 homework/data-access.ts(1038 行 → 分离排名逻辑)
修复 shared/lib ↔ auth 循环依赖
dashboard 改为通过各模块 data-access 获取数据
messaging 写通知改为通过 notifications dispatcher

短期执行(P1)

统一 classSchedule 写入口到 scheduling 模块
actions 层移除直接 DB 操作
拆分 auth.ts
集成 proctoring/exam-mode-config 到考试表单
拆分 users/import-export.ts

中期执行(P2)

建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
schema.ts 按业务域分节(加注释分隔)

4.8 KiB Raw Blame History