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 混入排名业务逻辑
actions 层职责	⚠️ 部分违规	exams/homework/questions 的 actions 直接访问 DB；textbooks/grades 的 actions 设计良好
组件耦合	✅ 基本合规	组件层跨模块依赖均为类型导入或 UI 组合，无直接 data-access 调用
跨模块依赖	⚠️ 存在风险	无循环依赖，但 exams→questions、homework→exams、grades→classes 的直接 DB 访问破坏封装
文件行数	❌ 存在违规	homework/data-access.ts 1038 行（超 1000 硬上限）；exams/ai-pipeline.ts 912 行、exams/actions.ts 832 行（超 800 建议值）

关键风险项

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

---

二、模块依赖关系图

                    ┌──────────────┐
                    │  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	832	≤800	⚠️ 超限
ai-pipeline.ts	912	≤800	⚠️ 超限
data-access.ts	339	≤800	✅
types.ts	31	无限制	✅
hooks/use-exam-preview.ts	295	≤500	✅

模块职责边界

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

data-access 层问题

函数	问题	严重程度
getExams	直接查询 classes 表获取教师 gradeIds（第 71-78 行）	高
getExamById	直接查询 classes 表获取教师 gradeIds（第 155-159 行）	高
persistAiGeneratedExamDraft	直接 insert 到 questions 表（第 317-326 行）	高

actions 层问题

函数	问题	严重程度
updateExamAction	直接 db.query.exams.findFirst 做归属校验 + db.delete/db.insert/db.update 操作 examQuestions	高
deleteExamAction	直接 db.query.exams.findFirst 做归属校验 + db.delete	高
duplicateExamAction	直接 db.query.exams.findFirst + db.transaction 内联 insert exams/examQuestions	高
getExamPreviewAction	直接 db.query.exams.findFirst 查询考试预览数据	高
getSubjectsAction	直接查询 subjects 表 —— 跨模块 DB 访问	高
getGradesAction	直接查询 grades 表 —— 跨模块 DB 访问	高

组件耦合

组件	问题	严重程度
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 问题

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

---

3.2 homework 模块

文件行数

文件	行数	限制	状态
data-access.ts	1038	≤1000 硬上限	❌ 必须拆分
actions.ts	387	≤800	✅
schema.ts	29	无限制	✅
types.ts	186	无限制	✅

模块职责边界

• 职责：作业全生命周期（创建/发布/作答/批改/分析）
• 问题：getStudentDashboardGrades 包含班级排名计算逻辑（150+ 行），属于 dashboard 或 grades 模块职责

data-access 层问题（严重）

函数	问题	严重程度
getStudentDashboardGrades	150+ 行排名计算业务逻辑混入 data-access	高
getHomeworkAssignmentAnalytics	145+ 行错误率/错误答案统计业务逻辑混入 data-access	高
getHomeworkAssignments	直接查询 exams 表（第 167-171 行）	高
getHomeworkAssignmentReviewList	直接查询 exams 表（第 227-233 行）	高
getHomeworkSubmissions	直接查询 exams 表（第 349-359 行）	高
getHomeworkAssignmentById	直接查询 exams 表（第 403-407 行）	高
getStudentHomeworkAssignments	直接 join exams/subjects 表（第 730-731 行）	高
getDemoStudentUser	直接查询 users/roles/usersToRoles 表 + 使用 auth() 而非 auth-guard	高
getStudentDashboardGrades	直接查询 classEnrollments/users 表	高

actions 层问题

函数	问题	严重程度
createHomeworkAssignmentAction	157 行，混合数据访问 + 业务逻辑 + 权限校验	高
同上	直接查询 classes/classSubjectTeachers/exams/classEnrollments 表	高
同上	内联 db.transaction insert homeworkAssignments/homeworkAssignmentQuestions/homeworkAssignmentTargets	高
startHomeworkSubmissionAction	直接 db.query + db.insert	高
saveHomeworkAnswerAction	直接 db.query + db.transaction	高
submitHomeworkAction	直接 db.query + db.update	高
gradeHomeworkSubmissionAction	直接 db.update 循环更新 homeworkAnswers	高

拆分建议

data-access.ts（1038 行）建议拆分为：

• data-access.ts：基础 CRUD（getHomeworkAssignments, getHomeworkAssignmentById, getHomeworkSubmissions）
• data-access-student.ts：学生视角查询（getStudentHomeworkAssignments, getStudentHomeworkTakeData, getStudentDashboardGrades）
• data-access-analytics.ts：分析统计（getHomeworkAssignmentAnalytics, getTeacherGradeTrends）
• data-access-grading.ts：批改相关（getHomeworkSubmissionDetails, getHomeworkAssignmentReviewList）

---

3.3 questions 模块

文件行数

文件	行数	限制	状态
actions.ts	294	≤800	✅
data-access.ts	129	≤800	✅
schema.ts	18	无限制	✅
types.ts	34	无限制	✅

模块职责边界

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

data-access 层问题

• ✅ 仅访问 questions 和 questionsToKnowledgePoints 表，无跨模块 DB 访问
• ❌ 缺失写操作函数：insertQuestionWithRelations、deleteQuestionRecursive 等 data-access 函数被错误地放在 actions.ts 中

actions 层问题

函数	问题	严重程度
createNestedQuestion	内联 db.transaction + 调用 insertQuestionWithRelations（data-access 函数错放在 actions）	高
updateQuestionAction	内联 db.transaction 做 update/delete/insert	高
deleteQuestionAction	内联 db.transaction + 调用 deleteQuestionRecursive（data-access 函数错放在 actions）	高
getKnowledgePointOptionsAction	直接查询 knowledgePoints/chapters/textbooks 表 —— 跨模块 DB 访问	高
getQuestionsAction	✅ 正确委托给 data-access.getQuestions	✅

组件耦合

• ✅ 无跨模块依赖

---

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

2. 消除跨模块直接 DB 访问

   • 在 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

   • updateExamAction、deleteExamAction、duplicateExamAction、getExamPreviewAction 的 DB 操作移至 data-access
   • 将 getSubjectsAction/getGradesAction 移至 school 模块或改为调用 school/data-access

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

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

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

   • insertQuestionWithRelations、deleteQuestionRecursive 移至 data-access
   • getKnowledgePointOptionsAction 改为调用 textbooks/data-access

5.2 中优先级（P1）

6. 拆分 exams/ai-pipeline.ts（912 行 → 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
   • getHomeworkAssignmentAnalytics 的错误率统计逻辑提取到 services/analytics-service.ts

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

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

9. 减少组件 props 数量

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

5.3 低优先级（P2）

10. 统一 auth 调用方式

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

11. 补全 questions/data-access.ts 的写操作

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

---

六、标杆模块推荐

模块	推荐参考点
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 数量和跨模块依赖）