NextEdu/docs/architecture/audit/core-business-audit.md

核心业务模块职责与耦合审查报告

审计日期：2026-06-17 审计范围：src/modules/exams、src/modules/homework、src/modules/questions、src/modules/textbooks、src/modules/grades 审计目标：识别职责不单一和过耦合问题，重点关注跨模块直接数据库查询（违反模块封装） 审计依据：项目规则（.trae/rules/project_rules.md）、架构影响地图（004/005）

---

一、总体结论

维度	状态	说明
模块职责边界	⚠️ 部分违规	homework 混入考试/班级逻辑；grades 混入班级/用户逻辑
data-access 层职责	❌ 普遍违规	5 个模块均存在跨模块直接 DB 查询；homework/data-access.ts 混入排名业务逻辑（已拆分 stats-service.ts）
actions 层职责	✅ 已修复	exams/homework/questions/announcements 的 actions DB 操作已下沉到 data-access（P1-2）；textbooks/grades 的 actions 设计良好
组件耦合	✅ 基本合规	组件层跨模块依赖均为类型导入或 UI 组合，无直接 data-access 调用
跨模块依赖	⚠️ 存在风险	无循环依赖，但 exams→questions、homework→exams、grades→classes 的直接 DB 访问破坏封装
文件行数	✅ 已修复	homework/data-access.ts 已拆分（598 行 + stats-service.ts 425 行 + data-access-write.ts 285 行）；exams/ai-pipeline.ts 857 行（超 800 建议值，P1 待拆分）

关键风险项

1. homework/data-access.ts 超过 1000 行硬上限（1038 行）—— 必须拆分 ✅ 已拆分
2. 5 个模块均存在跨模块直接 DB 查询 —— 违反模块封装原则（P1-1 待修复）
3. exams/homework/questions 的 actions 层混入数据访问逻辑 —— 应只做编排 ✅ 已修复（P1-2）
4. homework/data-access.ts 混入排名计算业务逻辑 —— data-access 应只负责数据存取 ✅ 已修复（拆分到 stats-service.ts）

---

二、模块依赖关系图

                    ┌──────────────┐
                    │  textbooks   │ ← 被引用方（知识点/章节）
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
            ▼              ▼              ▼
     ┌────────────┐  ┌──────────┐  ┌────────────┐
     │ questions  │  │  exams   │  │  homework  │
     └─────┬──────┘  └────┬─────┘  └─────┬──────┘
           │              │              │
           │   ┌──────────┘              │
           │   │                          │
           ▼   ▼                          ▼
     ┌────────────────┐            ┌──────────┐
     │    grades      │            │  classes │
     └────────────────┘            └──────────┘

依赖关系明细

依赖方向	类型	合理性	问题
exams → questions	data-access + 类型 + action	⚠️ 部分合理	类型导入合理；但 persistAiGeneratedExamDraft 直接 insert 到 questions 表，应通过 questions/data-access
exams → classes	data-access	❌ 不合理	getExams/getExamById 直接查询 classes 表获取教师 gradeIds，应通过 classes/data-access
exams → school	actions	❌ 不合理	getSubjectsAction/getGradesAction 直接查询 subjects/grades 表，应通过 school/data-access
homework → exams	data-access + 组件	⚠️ 部分合理	业务上 homework 引用 exam（sourceExamId）合理；但直接查询 exams 表应改为调用 exams/data-access
homework → classes	data-access + actions	❌ 不合理	直接查询 classes/classEnrollments/classSubjectTeachers 表，应通过 classes/data-access
homework → questions	data-access	✅ 合理	通过 Drizzle 关系查询 homeworkAssignmentQuestions.question，未直接访问 questions 表
grades → exams	无	✅ 合理	grades 仅通过 examId 外键引用，不直接查询 exams 表
grades → homework	无	✅ 合理	grades 仅通过 type 枚举值 "homework" 引用，不直接查询 homework 表
grades → classes	data-access	❌ 不合理	多个 data-access 文件直接查询 classes/classEnrollments 表
grades → users/subjects	data-access	❌ 不合理	直接查询 users/subjects 表获取关联名称，应通过对应模块 data-access
questions → textbooks	actions	❌ 不合理	getKnowledgePointOptionsAction 直接查询 knowledgePoints/chapters/textbooks 表
textbooks → questions	组件	✅ 合理	knowledge-point-dialogs.tsx 导入 CreateQuestionDialog 组件，属于 UI 组合

循环依赖分析

• 无直接循环依赖：模块间的 data-access 依赖是单向的
• 潜在风险：exams → questions（data-access）与 questions → textbooks（actions）与 textbooks → questions（组件）形成链式依赖，但因 textbooks→questions 仅为组件层导入，不构成 data-access 层的循环依赖

---

三、各模块审查明细

3.1 exams 模块

文件行数

文件	行数	限制	状态
actions.ts	691	≤800	✅（P1-2 后从 832 降至 691）
ai-pipeline.ts	857	≤800	⚠️ 超限（P1 待拆分）
data-access.ts	471	≤800	✅（P1-2 后从 339 扩展到 471）
types.ts	31	无限制	✅
hooks/use-exam-preview.ts	295	≤500	✅

模块职责边界

• 职责：考试全生命周期管理（创建/编辑/预览/发布/删除/复制）+ AI 辅助出题
• 问题：getSubjectsAction/getGradesAction 属于 school 模块职责，被放在 exams/actions.ts 中（P1-1 待修复）

data-access 层问题

函数	问题	严重程度
getExams	直接查询 classes 表获取教师 gradeIds	高（P1-1 待修复）
getExamById	直接查询 classes 表获取教师 gradeIds	高（P1-1 待修复）
persistAiGeneratedExamDraft	直接 insert 到 questions 表	高（P1-1 待修复）

actions 层问题 ✅ 已修复（P1-2）

exams/actions.ts 中的 DB 操作已下沉到 data-access

已完成修复（2026-06-17，commit 84d6636）：

• 新增 7 个 data-access 函数（updateExam / deleteExam / duplicateExam / getExamPreview 等）
• actions.ts 从 832 行降至 691 行
• data-access.ts 从 339 行扩展到 471 行
• actions 层不再有直接 db.insert/update/delete

组件耦合

组件	问题	严重程度
exam-assembly.tsx	调用 getQuestionsAction（questions 模块的 action）	中
8 个组件	导入 Question 类型自 questions/types	低（类型导入合理）
ExamAssembly	10 个 props（examId, title, subject, grade, difficulty, totalScore, durationMin, initialSelected, initialStructure, questionOptions）	中
ExamPreviewQuestionEditor	10 个 props	中

ai-pipeline.ts 问题

• 857 行，超过 800 行建议值（原 912 行，已部分优化）
• 混合了 Zod schema、AI prompt、JSON 解析修复、题目详情解析、并发控制等多种职责
• 建议拆分为：ai-schema.ts（Zod schema）、ai-prompts.ts（prompt 常量）、ai-parser.ts（JSON 解析修复）、ai-pipeline.ts（核心生成逻辑）（P1 待处理）

---

3.2 homework 模块

文件行数

文件	行数	限制	状态
data-access.ts	598	≤1000 硬上限	✅（P0-2 后从 1038 降至 598）
data-access-write.ts	285	≤800	✅（P1-2 新增，10 个写函数）
stats-service.ts	425	≤800	✅（P0-2 新增，统计业务逻辑）
actions.ts	239	≤800	✅（P1-2 后从 387 降至 239）
schema.ts	29	无限制	✅
types.ts	186	无限制	✅

模块职责边界

• 职责：作业全生命周期（创建/发布/作答/批改/分析）
• 问题：getStudentDashboardGrades 包含班级排名计算逻辑（已迁移到 stats-service.ts）

data-access 层问题（部分修复）

函数	问题	严重程度
getStudentDashboardGrades	150+ 行排名计算业务逻辑混入 data-access ✅ 已迁移到 stats-service.ts	✅ 已修复
getHomeworkAssignmentAnalytics	145+ 行错误率/错误答案统计业务逻辑混入 data-access ✅ 已迁移到 stats-service.ts	✅ 已修复
getHomeworkAssignments	直接查询 exams 表	高（P1-1 待修复）
getHomeworkAssignmentReviewList	直接查询 exams 表	高（P1-1 待修复）
getHomeworkSubmissions	直接查询 exams 表	高（P1-1 待修复）
getHomeworkAssignmentById	直接查询 exams 表	高（P1-1 待修复）
getStudentHomeworkAssignments	直接 join exams/subjects 表	高（P1-1 待修复）
getDemoStudentUser	直接查询 users/roles/usersToRoles 表 + 使用 auth() 而非 auth-guard	高（P1-1 待修复）
getStudentDashboardGrades	直接查询 classEnrollments/users 表	高（P1-1 待修复）

actions 层问题 ✅ 已修复（P1-2）

homework/actions.ts 中的 DB 操作已下沉到 data-access

已完成修复（2026-06-17，commit 84d6636）：

• 新建 data-access-write.ts（285 行，10 个写函数）
• actions.ts 从 387 行降至 239 行
• createHomeworkAssignmentAction 等 Action 的 DB 操作全部下沉到 data-access-write.ts
• actions 层不再有直接 db.insert/update/delete

拆分结果 ✅ 已完成

data-access.ts（原 1038 行）已拆分为：

• data-access.ts（598 行）：基础 CRUD + 查询
• data-access-write.ts（285 行）：写操作（10 个写函数）
• stats-service.ts（425 行）：统计业务逻辑（排名计算、错误率统计等）

---

3.3 questions 模块

文件行数

文件	行数	限制	状态
actions.ts	149	≤800	✅（P1-2 后从 294 降至 149）
data-access.ts	260	≤800	✅（P1-2 后从 129 扩展到 260）
schema.ts	18	无限制	✅
types.ts	34	无限制	✅

模块职责边界

• 职责：题库管理（题目 CRUD、知识点关联、题型支持）
• 问题：getKnowledgePointOptionsAction 查询 textbooks 模块的表，属于 textbooks 模块职责（P1-1 待修复）

data-access 层问题 ✅ 已修复（P1-2）

• ✅ 仅访问 questions 和 questionsToKnowledgePoints 表，无跨模块 DB 访问
• ✅ 写操作函数已补全：insertQuestionWithRelations、deleteQuestionRecursive 等 data-access 函数已从 actions.ts 迁移到 data-access.ts（data-access.ts 从 129 行扩展到 260 行）

actions 层问题 ✅ 已修复（P1-2）

questions/actions.ts 中的 DB 操作已下沉到 data-access

已完成修复（2026-06-17，commit 84d6636）：

• 新增 4 个 data-access 函数（insertQuestionWithRelations / deleteQuestionRecursive 等）
• actions.ts 从 294 行降至 149 行
• createNestedQuestion / updateQuestionAction / deleteQuestionAction 的 DB 操作全部下沉
• actions 层不再有直接 db.transaction

剩余问题：

• getKnowledgePointOptionsAction 仍直接查询 knowledgePoints/chapters/textbooks 表 —— 跨模块 DB 访问（P1-1 待修复）

组件耦合

• ✅ 无跨模块依赖

---

3.4 textbooks 模块（标杆模块）

文件行数

文件	行数	限制	状态
actions.ts	276	≤800	✅
data-access.ts	428	≤800	✅
types.ts	79	无限制	✅
hooks/use-knowledge-point-actions.ts	121	≤500	✅
hooks/use-text-selection.ts	-	≤500	✅

模块职责边界

• 职责：教材与知识体系管理（教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱）
• ✅ 职责单一，无越界

data-access 层评价

• ✅ 仅访问 textbooks、chapters、knowledgePoints 表
• ✅ 无跨模块 DB 访问
• ✅ 无业务逻辑混入

actions 层评价

• ✅ 标杆实现：所有 action 均遵循"权限校验 → 调用 data-access → revalidatePath → 返回"模式
• ✅ 无直接 DB 访问
• ✅ 无业务逻辑混入

组件耦合

• knowledge-point-dialogs.tsx 导入 CreateQuestionDialog 自 questions 模块 —— ✅ 合理的 UI 组合

hooks 评价

• useKnowledgePointActions 有 7 个参数（textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated）—— ✅ 在 8 个限制内

---

3.5 grades 模块

文件行数

文件	行数	限制	状态
actions.ts	312	≤800	✅
actions-analytics.ts	133	≤800	✅
data-access.ts	419	≤800	✅
data-access-analytics.ts	293	≤800	✅
data-access-ranking.ts	121	≤800	✅
export.ts	214	≤800	✅
schema.ts	52	无限制	✅
types.ts	-	无限制	✅

模块职责边界

• 职责：成绩分析（录入/查询/统计/导出/趋势对比分析）
• ✅ 职责单一，未混入考试/作业逻辑
• ✅ 通过 examId 外键引用考试，通过 type 枚举引用作业类型，未直接依赖 exams/homework 模块的 data-access

data-access 层问题

文件	函数	问题	严重程度
data-access.ts	getGradeRecords	直接 join classes/subjects/users 表	高
data-access.ts	getStudentGradeSummary	直接 join classes/subjects/users 表	高
data-access.ts	getClassRanking	直接 join users 表	高
data-access.ts	getClassStudentsForEntry	直接查询 classEnrollments/users 表 —— 应在 classes 模块	高
data-access.ts	getClassGradeStatsWithMeta	直接查询 classes/classEnrollments 表	高
data-access.ts	getClassGradeStats	统计计算业务逻辑（average/median/stdDev/passRate/excellentRate）混入 data-access	中
data-access-analytics.ts	getGradeTrend	直接 join classes/subjects 表	高
data-access-analytics.ts	getClassComparison	直接查询 classes 表 + 统计计算业务逻辑	高
data-access-analytics.ts	getSubjectComparison	直接 join subjects 表 + 统计计算业务逻辑	高
data-access-analytics.ts	getGradeDistribution	分桶统计业务逻辑混入 data-access	中
data-access-ranking.ts	getRankingTrend	直接查询 classEnrollments/users 表 + 排名计算业务逻辑	高
export.ts	exportClassGradeReportToExcel	直接查询 classes/subjects/users 表 + 排名计算业务逻辑	高

actions 层评价

• ✅ 标杆实现：actions.ts 和 actions-analytics.ts 均遵循"权限校验 → 调用 data-access → 返回"模式
• ✅ 无直接 DB 访问
• ✅ 无业务逻辑混入

组件耦合

• ✅ 无跨模块依赖

---

四、跨模块直接 DB 访问汇总

以下为违反模块封装原则的直接数据库查询，应改为通过对方模块的 data-access 函数调用。

4.1 按来源模块分类

来源模块	文件	被访问的表	应调用的模块
exams	data-access.ts	classes	classes/data-access
exams	data-access.ts	questions（insert）	questions/data-access
exams	actions.ts	subjects, grades	school/data-access
homework	actions.ts	classes, classSubjectTeachers, exams, classEnrollments	classes/data-access, exams/data-access
homework	data-access.ts	exams, classEnrollments, subjects, users, roles, usersToRoles	exams/data-access, classes/data-access, school/data-access
questions	actions.ts	knowledgePoints, chapters, textbooks	textbooks/data-access
grades	data-access.ts	classes, classEnrollments, subjects, users	classes/data-access, school/data-access
grades	data-access-analytics.ts	classes, subjects	classes/data-access, school/data-access
grades	data-access-ranking.ts	classEnrollments, users	classes/data-access
grades	export.ts	classes, subjects, users	classes/data-access, school/data-access

4.2 按被访问表分类（频次）

被访问表	访问次数	应归属模块
classes	8+	classes
classEnrollments	6+	classes
users	6+	users
subjects	6+	school
exams	5+	exams
grades（年级表）	1	school
classSubjectTeachers	1	classes
knowledgePoints	1	textbooks
chapters	1	textbooks
textbooks	1	textbooks
roles, usersToRoles	1	users
questions（insert）	1	questions

---

五、改进建议

5.1 高优先级（P0）

1. 拆分 homework/data-access.ts（1038 行 → 4 个文件） ✅ 已完成

   • 按职责拆分为 data-access.ts / data-access-student.ts / data-access-analytics.ts / data-access-grading.ts
   • 实际拆分为 data-access.ts（598 行）+ data-access-write.ts（285 行）+ stats-service.ts（425 行）

2. 消除跨模块直接 DB 访问（P1-1 待修复）

   • 在 classes/data-access 暴露 getClassGradeIdsByClassIds、getClassStudentsByClassId、getActiveClassStudents 等函数
   • 在 exams/data-access 暴露 getExamForHomeworkCreation（含 questions 关联）
   • 在 school/data-access 暴露 getSubjectOptions、getGradeOptions
   • 在 users/data-access 暴露 getUserNameByIds、getStudentInfo
   • 在 textbooks/data-access 暴露 getKnowledgePointOptions
   • 在 questions/data-access 暴露 insertQuestionWithRelations、deleteQuestionRecursive

3. 将 exams/actions.ts 中的 DB 操作下沉到 data-access ✅ 已完成（P1-2）

   • updateExamAction、deleteExamAction、duplicateExamAction、getExamPreviewAction 的 DB 操作移至 data-access
   • 将 getSubjectsAction/getGradesAction 移至 school 模块或改为调用 school/data-access（P1-1 待修复）

4. 将 homework/actions.ts 中的 DB 操作下沉到 data-access ✅ 已完成（P1-2）

   • createHomeworkAssignmentAction（157 行）拆分为：data-access 函数 + action 编排
   • 其他 action 的 DB 操作全部移至 data-access

5. 将 questions/actions.ts 中的 DB 操作下沉到 data-access ✅ 已完成（P1-2）

   • insertQuestionWithRelations、deleteQuestionRecursive 移至 data-access
   • getKnowledgePointOptionsAction 改为调用 textbooks/data-access（P1-1 待修复）

5.2 中优先级（P1）

6. 拆分 exams/ai-pipeline.ts（857 行 → 4 个文件）

   • ai-schema.ts（Zod schema）、ai-prompts.ts（prompt 常量）、ai-parser.ts（JSON 解析修复）、ai-pipeline.ts（核心生成逻辑）

7. 将 homework/data-access.ts 中的业务逻辑提取到独立服务层 ✅ 已完成

   • getStudentDashboardGrades 的排名计算逻辑提取到 services/ranking-service.ts → 实际提取到 stats-service.ts
   • getHomeworkAssignmentAnalytics 的错误率统计逻辑提取到 services/analytics-service.ts → 实际提取到 stats-service.ts

8. 将 grades/data-access.ts 中的统计计算逻辑提取到独立服务层（P1 待处理）

   • getClassGradeStats 的统计计算提取到 services/stats-service.ts
   • getGradeDistribution 的分桶逻辑提取到 services/distribution-service.ts

9. 减少组件 props 数量（P2 待处理）

   • ExamAssembly（10 props）和 ExamPreviewQuestionEditor（10 props）应考虑使用 Context 或组合模式减少 props

5.3 低优先级（P2）

10. 统一 auth 调用方式（P2 待处理）

    • homework/data-access.ts 的 getDemoStudentUser 使用 auth() 而非 auth-guard.getAuthContext()，应统一

11. 补全 questions/data-access.ts 的写操作 ✅ 已完成（P1-2）

    • 当前 data-access 仅有 getQuestions，所有写操作错放在 actions.ts → 写操作已下沉到 data-access

---

六、标杆模块推荐

模块	推荐参考点
textbooks	actions 层编排模式（权限校验 → 调用 data-access → revalidatePath）
textbooks	data-access 层职责单一（仅访问本模块表，无业务逻辑）
grades	actions 层拆分（actions.ts + actions-analytics.ts 按职责分文件）
grades	data-access 层拆分（data-access.ts + data-access-analytics.ts + data-access-ranking.ts）
grades	跨模块解耦（通过外键引用 exams/homework，不直接访问其表）

---

七、审查方法说明

• 审查范围：5 个核心业务模块的 actions/data-access/schema/types/components/hooks 全量文件
• 审查工具：源码全量阅读 + Grep 跨模块依赖扫描 + PowerShell 行数统计
• 审查依据：项目规则中"Server Action 必须使用 requirePermission()"、"单文件行数规范"、"模块职责单一"等规则
• 未覆盖项：未运行 lint/typecheck（本次为只读审查，不修改代码）；未审查组件内部实现细节（仅审查 props 数量和跨模块依赖）