CICD/docs/design/005_exam_module_implementation.md

考试模块实现设计文档

1. 概述

考试模块用于教师侧的“试卷制作与管理”，覆盖创建考试、组卷（支持嵌套分组）、发布/归档等流程。

说明（合并调整）：与“作业（Homework）”模块合并后，考试模块不再提供“阅卷/评分（grading）”与提交流转；教师批改统一在 Homework 的 submissions 中完成。

2. 数据架构

2.1 核心实体

• Exams: 根实体，包含元数据（标题、时间安排）和结构信息。
• ExamQuestions: 关系链接，用于查询题目的使用情况（扁平化表示）。
• ExamSubmissions: （历史/保留）学生的考试尝试记录；当前 UI/路由不再使用。
• SubmissionAnswers: （历史/保留）链接到特定题目的单个答案；当前 UI/路由不再使用。

2.2 structure 字段

为了支持层级布局（如章节/分组），我们在 exams 表中引入了一个 JSON 列 structure。它作为“布局/呈现层”的单一事实来源（Source of Truth），用于渲染分组与排序；而 exam_questions 仍然承担题目关联、外键完整性与索引查询职责。

JSON Schema:

type ExamNode = {
  id: string;              // 节点的唯一 UUID
  type: 'group' | 'question';
  title?: string;          // 'group' 类型必填
  questionId?: string;     // 'question' 类型必填
  score?: number;          // 在此考试上下文中的分值
  children?: ExamNode[];   // 'group' 类型的递归子节点
}

2.3 description 元数据字段（当前实现）

当前版本将部分元数据（如 subject/grade/difficulty/totalScore/durationMin/tags/scheduledAt）以 JSON 字符串形式存入 exams.description，并在数据访问层解析后提供给列表页展示与筛选。

3. 组件架构

3.1 组卷（构建器）

位于 /teacher/exams/[id]/build。

• ExamAssembly (客户端组件)
  • 管理 structure 状态树。
  • 处理“添加题目”、“添加章节”、“移除”和“重新排序”操作。
  • 实时计算总分和进度。
• StructureEditor (客户端组件)
  • 基于 @dnd-kit 构建。
  • 提供嵌套的可排序（Sortable）界面。
  • 支持在组内/组间拖拽题目（当前优化为 2 层深度）。
• QuestionBankList
  • 可搜索/筛选的可用题目列表。
  • “添加”操作将节点追加到结构树中。

3.2 阅卷界面（已下线）

原阅卷路由 /teacher/exams/grading 与 /teacher/exams/grading/[submissionId] 已移除业务能力并重定向到 Homework：

• /teacher/exams/grading* → /teacher/homework/submissions

3.3 列表页（All Exams）

位于 /teacher/exams/all。

• Page (RSC): 负责解析 query（q/status/difficulty）并调用数据访问层获取 exams。
• ExamFilters (客户端组件): 使用 URL query 驱动筛选条件。
• ExamDataTable (客户端组件): 基于 TanStack Table 渲染列表，并在 actions 列中渲染 ExamActions。

4. 关键工作流

4.1 创建与构建考试

1. 创建: 教师输入基本信息（标题、科目）。数据库创建记录（草稿状态）。
2. 构建:
   • 教师打开“构建”页面。
   • 服务器从数据库 Hydrate（注水）initialStructure。
   • 教师从题库拖拽题目到结构树。
   • 教师创建章节（分组）。
   • 保存: 同时提交 questionsJson（扁平化，用于索引）和 structureJson（树状，用于布局）到 updateExamAction。
3. 发布: 状态变更为 published。

4.2 阅卷/批改流程（迁移到 Homework）

教师批改统一在 Homework 模块完成：

• 提交列表：/teacher/homework/submissions
• 批改页：/teacher/homework/submissions/[submissionId]

4.3 考试管理（All Exams Actions）

位于 /teacher/exams/all 的表格行级菜单。

1. Publish / Move to Draft / Archive

   • 客户端组件 ExamActions 触发 updateExamAction，传入 examId 与目标 status。
   • 服务器更新 exams.status，并对 /teacher/exams/all 执行缓存再验证。

2. Duplicate

   • 客户端组件 ExamActions 触发 duplicateExamAction，传入 examId。
   • 服务器复制 exams 记录并复制关联的 exam_questions。
   • 新考试以 draft 状态创建，复制结构（exams.structure），并清空排期信息（startTime/endTime，以及 description 中的 scheduledAt）。
   • 成功后跳转到新考试的构建页 /teacher/exams/[id]/build。

3. Delete

   • 客户端组件 ExamActions 触发 deleteExamAction，传入 examId。
   • 服务器删除 exams 记录；相关表（如 exam_questions、exam_submissions、submission_answers）通过外键级联删除。
   • 成功后刷新列表。

4. Edit / Build

   • 当前统一跳转到 /teacher/exams/[id]/build。

5. 技术决策

5.1 混合存储策略

我们在存储考试题目时采用了 混合方法：

• 关系型 (exam_questions): 用于“查找所有使用题目 X 的考试”查询和外键约束。
• 文档型 (exams.structure): 用于渲染嵌套 UI 和保留任意排序/分组。 理由: 这结合了 SQL 的完整性和 NoSQL 在 UI 布局上的灵活性。

5.2 拖拽功能

使用 @dnd-kit 代替旧库，因为：

• 更好的无障碍支持（键盘支持）。
• 模块化架构（Sensors, Modifiers）。
• 面向未来（现代 React Hooks 模式）。

5.3 Server Actions

所有变更操作（保存草稿、发布、复制、删除）均使用 Next.js Server Actions，以确保类型安全并自动重新验证缓存。

已落地的 Server Actions：

• createExamAction
• updateExamAction
• duplicateExamAction
• deleteExamAction

6. 接口与数据影响

6.1 updateExamAction

• 入参（FormData）: examId（必填），status（可选：draft/published/archived），questionsJson（可选），structureJson（可选）
• 行为:
  • 若传入 questionsJson：先清空 exam_questions 再批量写入，order 由数组顺序决定；未传入则不触碰 exam_questions
  • 若传入 structureJson：写入 exams.structure；未传入则不更新该字段
  • 若传入 status：写入 exams.status
• 缓存: revalidatePath("/teacher/exams/all")

6.2 duplicateExamAction

• 入参（FormData）: examId（必填）
• 行为:
  • 复制一条 exams（新 id、新 title：追加 “(Copy)”、status 强制为 draft）
  • startTime/endTime 置空；同时尝试从 description JSON 中移除 scheduledAt
  • 复制 exam_questions（保留 questionId/score/order）
  • 复制 exams.structure
• 缓存: revalidatePath("/teacher/exams/all")

6.3 deleteExamAction

• 入参（FormData）: examId（必填）
• 行为:
  • 删除 exams 记录
  • 依赖外键级联清理关联数据：exam_questions、exam_submissions、submission_answers
• 缓存:
  • revalidatePath("/teacher/exams/all")

6.4 数据访问层（Data Access）

位于 src/modules/exams/data-access.ts，对外提供与页面/组件解耦的查询函数。

• getExams(params): 支持按 q/status 在数据库侧过滤；difficulty 因当前存储在 description JSON 中，采用内存过滤
• getExamById(id): 查询 exam 及其 exam_questions，并返回 structure 以用于构建器 Hydrate

7. 变更记录（合并 Homework）

日期：2025-12-31

• 移除 Exams grading 入口与实现：删除阅卷 UI、server action、data-access 查询。
• Exams grading 路由改为重定向到 Homework submissions。