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
This commit is contained in:
SpecialX
132
docs/architecture/audit/00_summary.md
Normal file
132
docs/architecture/audit/00_summary.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# 架构审查汇总报告
|
||||
|
||||
> 基于对全项目 69+ 文件的逐文件审查,汇总关键架构问题。
|
||||
> 审查日期: 2026-06-17
|
||||
> 子报告:
|
||||
> - [shared 基础设施层审查](./shared-audit.md)
|
||||
> - [核心业务模块审查](./core-business-audit.md)
|
||||
> - [管理模块群审查](./management-modules-audit.md)
|
||||
> - [新增模块和其他模块审查](./new-and-other-modules-audit.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、总体评估
|
||||
|
||||
| 维度 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 模块化程度 | ⚠️ 中等 | 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 文档的问题
|
||||
|
||||
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 个文件)
|
||||
2. 拆分 `homework/data-access.ts`(1038 行 → 分离排名逻辑)
|
||||
3. 修复 shared/lib ↔ auth 循环依赖
|
||||
4. dashboard 改为通过各模块 data-access 获取数据
|
||||
5. messaging 写通知改为通过 notifications dispatcher
|
||||
|
||||
### 短期执行(P1)
|
||||
6. 统一 classSchedule 写入口到 scheduling 模块
|
||||
7. actions 层移除直接 DB 操作
|
||||
8. 拆分 auth.ts
|
||||
9. 集成 proctoring/exam-mode-config 到考试表单
|
||||
10. 拆分 users/import-export.ts
|
||||
|
||||
### 中期执行(P2)
|
||||
11. 建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
|
||||
12. schema.ts 按业务域分节(加注释分隔)
|
||||
Reference in New Issue
Block a user