docs: 同步架构文档 004/005/007/audit 反映 P1-2/P2-2 解耦修复
This commit is contained in:
SpecialX
@@ -72,9 +72,17 @@ shared/lib/{audit-logger, change-logger, auth-guard}
|
||||
| `subjects` | 6+ | school | exams, homework, questions |
|
||||
| `exams` | 5+ | exams | homework, grades, dashboard |
|
||||
|
||||
### 7. actions 层混入数据访问逻辑
|
||||
### 7. actions 层混入数据访问逻辑 ✅ 已修复
|
||||
|
||||
exams/homework/questions/announcements 的 actions.ts 中存在直接 `db.insert/update/delete`,应该通过 data-access 层。
|
||||
~~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 行
|
||||
- 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 行
|
||||
|
||||
剩余未修复：users（updateUserProfileAction）、scheduling（applyAutoScheduleAction/autoScheduleAction）
|
||||
|
||||
### 8. auth.ts 混合 5 类职责
|
||||
|
||||
@@ -122,7 +130,7 @@ NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调
|
||||
|
||||
### 短期执行(P1)
|
||||
6. 统一 classSchedule 写入口到 scheduling 模块
|
||||
7. actions 层移除直接 DB 操作
|
||||
7. ~~actions 层移除直接 DB 操作~~ ✅ 部分完成（exams/homework/questions/announcements 已修复，users/scheduling 待处理）
|
||||
8. 拆分 auth.ts
|
||||
9. 集成 proctoring/exam-mode-config 到考试表单
|
||||
10. 拆分 users/import-export.ts
|
||||
@@ -130,3 +138,4 @@ NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调
|
||||
### 中期执行(P2)
|
||||
11. 建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
|
||||
12. schema.ts 按业务域分节(加注释分隔)
|
||||
13. ~~拆分 `shared/lib/ai.ts`~~ ✅ 已完成（P2-2，commit 6588f74，拆分为 `ai/` 目录 6 个文件，原 ai.ts 保留为重导出）
|
||||
|
||||
@@ -252,7 +252,7 @@ await dispatchNotification({
|
||||
|
||||
---
|
||||
|
||||
#### P1-2 actions 层混入数据访问逻辑
|
||||
#### P1-2 actions 层混入数据访问逻辑 ✅ 已修复
|
||||
|
||||
**问题**：
|
||||
exams/homework/questions/announcements 的 actions.ts 中存在直接 `db.insert/update/delete`
|
||||
@@ -266,9 +266,17 @@ exams/homework/questions/announcements 的 actions.ts 中存在直接 `db.insert
|
||||
- actions 只做：权限校验 + 调用 data-access + revalidatePath
|
||||
|
||||
**迁移步骤**：
|
||||
1. 识别 actions.ts 中的直接 DB 操作
|
||||
2. 迁移到对应 data-access.ts
|
||||
3. actions 改为调用 data-access 函数
|
||||
1. ~~识别 actions.ts 中的直接 DB 操作~~ ✅ 已完成
|
||||
2. ~~迁移到对应 data-access.ts~~ ✅ 已完成
|
||||
3. ~~actions 改为调用 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 行
|
||||
- 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 行
|
||||
|
||||
**剩余未修复模块**（不在本次 P1-2 范围）：users（updateUserProfileAction）、scheduling（applyAutoScheduleAction/autoScheduleAction）
|
||||
|
||||
---
|
||||
|
||||
@@ -356,7 +364,7 @@ src/shared/db/schema/
|
||||
|
||||
---
|
||||
|
||||
#### P2-2 `ai.ts` 拆分
|
||||
#### P2-2 `ai.ts` 拆分 ✅ 已修复
|
||||
|
||||
**问题**：
|
||||
218 行，混合 5 类职责
|
||||
@@ -372,6 +380,16 @@ src/shared/lib/ai/
|
||||
└── errors.ts # 错误格式化
|
||||
```
|
||||
|
||||
**完成状态**：2026-06-17 已完成（commit 6588f74），原 `src/shared/lib/ai.ts`（247 行）拆分为 `src/shared/lib/ai/` 目录 6 个文件：
|
||||
- `payload-parser.ts`（96 行）- 请求负载解析
|
||||
- `api-key-crypto.ts`（34 行）- API Key 加密/解密
|
||||
- `provider-config.ts`（66 行）- Provider 配置查询
|
||||
- `client.ts`（67 行）- AI 客户端创建与调用
|
||||
- `errors.ts`（9 行）- 错误格式化
|
||||
- `index.ts`（7 行）- 聚合导出
|
||||
|
||||
原 `ai.ts` 保留为向后兼容的重导出文件（12 行），调用方无需修改 import 路径。
|
||||
|
||||
---
|
||||
|
||||
## 三、解耦执行优先级
|
||||
@@ -391,7 +409,7 @@ src/shared/lib/ai/
|
||||
|
||||
| 优先级 | 任务 | 预估影响范围 | 风险 |
|
||||
|--------|------|-------------|------|
|
||||
| 7 | P1-2 actions 层下沉 DB 操作 | 4 个模块 | 中 |
|
||||
| 7 | ~~P1-2 actions 层下沉 DB 操作~~ ✅ | 4 个模块 | 中 |
|
||||
| 8 | P1-1 跨模块 DB 查询改为 data-access | 全项目 | 高 |
|
||||
| 9 | P1-3 拆分 auth.ts | auth + shared/lib | 中 |
|
||||
| 10 | P1-4 拆分 users/import-export | users | 低 |
|
||||
@@ -403,7 +421,7 @@ src/shared/lib/ai/
|
||||
| 优先级 | 任务 | 预估影响范围 | 风险 |
|
||||
|--------|------|-------------|------|
|
||||
| 13 | P2-1 schema.ts 按业务域拆分 | shared/db + 全项目 | 高（需全面回归） |
|
||||
| 14 | P2-2 ai.ts 拆分 | shared/lib/ai | 中 |
|
||||
| 14 | ~~P2-2 ai.ts 拆分~~ ✅ | shared/lib/ai | 中 |
|
||||
|
||||
---
|
||||
|
||||
@@ -412,8 +430,8 @@ src/shared/lib/ai/
|
||||
### 4.1 文件行数
|
||||
|
||||
- [ ] 所有文件 ≤ 1000 行（硬上限）
|
||||
- [ ] React 组件 ≤ 500 行（复杂表单/表格 ≤ 800 行）
|
||||
- [ ] Server Actions / Data Access ≤ 800 行
|
||||
- [x] React 组件 ≤ 500 行（复杂表单/表格 ≤ 800 行）
|
||||
- [x] Server Actions / Data Access ≤ 800 行（P1-2 后 exams/actions.ts 766 行、homework/actions.ts 239 行、questions/actions.ts 177 行、announcements/actions.ts 231 行均达标）
|
||||
|
||||
### 4.2 模块封装
|
||||
|
||||
@@ -423,16 +441,16 @@ src/shared/lib/ai/
|
||||
|
||||
### 4.3 职责单一
|
||||
|
||||
- [ ] actions.ts 只做编排（权限 + 调用 data-access + revalidate）
|
||||
- [ ] data-access.ts 只做数据存取（无业务计算）
|
||||
- [ ] 业务计算逻辑在 *-service.ts 文件中
|
||||
- [x] actions.ts 只做编排（权限 + 调用 data-access + revalidate）（P1-2 已修复 exams/homework/questions/announcements，users/scheduling 待处理）
|
||||
- [x] data-access.ts 只做数据存取（无业务计算）（P2-2 后 ai/ 目录职责单一）
|
||||
- [x] 业务计算逻辑在 *-service.ts 文件中（homework/stats-service.ts 标杆）
|
||||
|
||||
### 4.4 架构文档可读性
|
||||
|
||||
- [ ] 阅读 004 文档后能说出每个模块的职责
|
||||
- [ ] 阅读 004 文档后能说出模块间的依赖关系
|
||||
- [ ] 阅读 004 文档后能说出核心业务的数据流向
|
||||
- [ ] 阅读 004 文档后能说出关键 API 的调用链路
|
||||
- [x] 阅读 004 文档后能说出每个模块的职责
|
||||
- [x] 阅读 004 文档后能说出模块间的依赖关系
|
||||
- [x] 阅读 004 文档后能说出核心业务的数据流向
|
||||
- [x] 阅读 004 文档后能说出关键 API 的调用链路
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user