docs: 全文档合规检查与修正 - 代码示例规范/行数准确性/路径一致性/状态同步
This commit is contained in:
SpecialX
@@ -15,10 +15,10 @@
|
||||
| 维度 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 模块化程度 | ⚠️ 中等 | 20+ 模块划分合理,但跨模块直接 DB 查询普遍存在 |
|
||||
| 职责单一性 | ⚠️ 中等 | 多数模块职责清晰,但 5 个文件超 1000 行硬上限 |
|
||||
| 职责单一性 | ✅ 良好 | 多数模块职责清晰,文件超 1000 行问题已修复（仅 schema.ts 保留） |
|
||||
| 架构文档质量 | ❌ 不足 | 004 文档按模块罗列函数,缺乏关系图/数据流/调用链 |
|
||||
| 循环依赖 | ❌ 存在 | shared/lib ↔ auth 循环依赖 |
|
||||
| 死代码 | ⚠️ 少量 | proctoring/exam-mode-config.tsx 未集成 |
|
||||
| 循环依赖 | ✅ 已修复 | shared/lib ↔ auth 循环依赖通过动态 import 打破 |
|
||||
| 死代码 | ⚠️ 用户保留 | proctoring/exam-mode-config.tsx 未集成（用户决定保留） |
|
||||
|
||||
**核心结论**: 架构设计思路正确(模块化 + 分层),但执行不够严格。主要问题是跨模块直接 DB 查询破坏了模块封装,以及少数文件过大。
|
||||
|
||||
@@ -26,37 +26,39 @@
|
||||
|
||||
## 二、P0 严重问题(必须修复)
|
||||
|
||||
### 1. 文件超 1000 行硬上限(3 个文件)
|
||||
### 1. 文件超 1000 行硬上限 ✅ 已修复
|
||||
|
||||
| 文件 | 行数 | 问题 |
|
||||
|------|------|------|
|
||||
| ~~`classes/data-access.ts`~~ | ~~2104~~ → 656 | ~~混入 homework/scheduling/grades 逻辑~~ ✅ 已拆分为 5 个文件 |
|
||||
| ~~`homework/data-access.ts`~~ | ~~1038~~ → 596 | ~~混入排名计算业务逻辑~~ ✅ 已拆分 |
|
||||
| `shared/db/schema.ts` | 1111 | 54 张表混合(可接受,但需分节) |
|
||||
| ~~`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. 循环依赖
|
||||
### 2. 循环依赖 ✅ 已修复
|
||||
|
||||
```
|
||||
shared/lib/{audit-logger, change-logger, auth-guard}
|
||||
→ @/auth (src/auth.ts)
|
||||
→ shared/lib/* (循环)
|
||||
```
|
||||
~~shared/lib/{audit-logger, change-logger, auth-guard} → @/auth (src/auth.ts) → shared/lib/* (循环)~~
|
||||
|
||||
### 3. dashboard 跨模块直接查询 11 张表
|
||||
**已完成修复**（2026-06-17）：3 个 logger/guard 文件改用动态 `import("@/auth")` 打破模块级静态循环依赖。
|
||||
|
||||
`dashboard/data-access.ts` 的 `getAdminDashboardData` 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装。
|
||||
### 3. dashboard 跨模块直接查询 11 张表 ✅ 已修复
|
||||
|
||||
### 4. messaging 绕过 notifications 直接写通知
|
||||
~~`dashboard/data-access.ts` 的 `getAdminDashboardData` 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装。~~
|
||||
|
||||
`messaging/actions.ts` 第 66-72 行直接调用 `createNotification`,导致用户通知偏好失效、多渠道通知无效。
|
||||
**已完成修复**（2026-06-17）：dashboard/data-access.ts 改为并行调用各模块的 `get[Module]DashboardStats()` 函数（42 行），不再直接查询任何业务表。
|
||||
|
||||
### 5. classSchedule 表三处写入口
|
||||
### 4. messaging 绕过 notifications 直接写通知 ✅ 已修复
|
||||
|
||||
- `classes/data-access.ts`
|
||||
- `scheduling/actions.ts` (直接 transaction 写入)
|
||||
- `scheduling/data-access.ts`
|
||||
~~`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 写入。
|
||||
|
||||
---
|
||||
|
||||
@@ -77,25 +79,40 @@ shared/lib/{audit-logger, change-logger, auth-guard}
|
||||
~~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 831→766 行，data-access.ts 374→524 行
|
||||
- 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→177 行，data-access.ts 138→299 行
|
||||
- announcements：新增 5 个 data-access 函数，actions.ts 242→231 行，data-access.ts 120→186 行
|
||||
- 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 类职责
|
||||
### 8. auth.ts 混合 5 类职责 ✅ 已修复
|
||||
|
||||
NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数,应拆分。
|
||||
~~NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数,应拆分。~~
|
||||
|
||||
### 9. users/import-export.ts 四重职责
|
||||
**已完成修复**（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 解析
|
||||
|
||||
导入解析 + 导出 + 用户创建(含密码哈希) + 班级注册(跨模块写 classEnrollments)。
|
||||
auth.ts 从 293 行降至 193 行，仅保留 NextAuth 配置。
|
||||
|
||||
### 10. proctoring 死代码
|
||||
### 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 字段但表单不收集。
|
||||
|
||||
**状态**：用户决定保留该组件，暂不集成也不删除。
|
||||
|
||||
---
|
||||
|
||||
## 四、架构文档问题
|
||||
@@ -123,17 +140,17 @@ NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调
|
||||
|
||||
### 立即执行(P0)
|
||||
1. ~~拆分 `classes/data-access.ts`(2104 行 → 按职责拆 3-4 个文件)~~ ✅ 已完成（拆为 5 个文件，均 ≤800 行）
|
||||
2. ~~拆分 `homework/data-access.ts`(1038 行 → 分离排名逻辑)~~ ✅ 已完成
|
||||
3. 修复 shared/lib ↔ auth 循环依赖
|
||||
4. dashboard 改为通过各模块 data-access 获取数据
|
||||
5. messaging 写通知改为通过 notifications dispatcher
|
||||
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 模块
|
||||
6. ~~统一 classSchedule 写入口到 scheduling 模块~~ ✅ 已完成（replaceClassSchedule 统一入口）
|
||||
7. ~~actions 层移除直接 DB 操作~~ ✅ 部分完成（exams/homework/questions/announcements 已修复，users/scheduling 待处理）
|
||||
8. 拆分 auth.ts
|
||||
9. 集成 proctoring/exam-mode-config 到考试表单
|
||||
10. 拆分 users/import-export.ts
|
||||
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 或导出查询函数)
|
||||
|
||||
Reference in New Issue
Block a user