CICD/docs/design/006_homework_module_implementation.md

作业模块实现设计文档（Homework Module）

日期: 2025-12-31
模块: Homework (src/modules/homework)

---

1. 概述

作业模块提供“由试卷派发作业”的完整生命周期：

• 教师从已存在的 Exam 派发 Homework Assignment（冻结当时的结构与题目引用）
• 指定作业目标学生（Targets）
• 学生开始一次作答（Submission），保存答案（Answers），并最终提交
• 教师在提交列表中查看并批改（按题给分/反馈，汇总总分）

核心目标是：在不破坏 Exam 本体数据的前提下，为作业提供可追溯、可批改、可统计的独立域模型。

说明（合并调整）：教师端“阅卷/批改”统一通过 Homework submissions 完成，/teacher/exams/grading* 相关路由已重定向到 /teacher/homework/submissions。

---

2. 数据架构

2.1 核心实体

• homework_assignments: 作业实例（从 exam 派生）
• homework_assignment_questions: 作业与题目关系（score/order）
• homework_assignment_targets: 作业目标学生列表
• homework_submissions: 学生作业尝试（attempt_no/status/时间/是否迟交）
• homework_answers: 每题答案（answer_content/score/feedback）

数据库变更记录见：schema-changelog.md

2.2 设计要点：冻结 Exam → Homework Assignment

• homework_assignments.source_exam_id 保存来源 Exam
• homework_assignments.structure 在 publish 时复制 exams.structure（冻结当时的呈现结构）
• 题目关联使用 homework_assignment_questions（仍引用 questions 表，作业侧记录分值与顺序）

---

3. 路由与页面

3.1 教师端

• /teacher/homework/assignments: 作业列表
  实现：assignments/page.tsx
• /teacher/homework/assignments/create: 从 Exam 派发作业
  实现：create/page.tsx
• /teacher/homework/assignments/[id]: 作业详情
  实现：[id]/page.tsx
• /teacher/homework/assignments/[id]/submissions: 作业提交列表（按作业筛选）
  实现：[id]/submissions/page.tsx
• /teacher/homework/submissions: 全部提交列表
  实现：submissions/page.tsx
• /teacher/homework/submissions/[submissionId]: 批改页
  实现：[submissionId]/page.tsx

关联重定向：

• /teacher/exams/grading → /teacher/homework/submissions
  实现：grading/page.tsx
• /teacher/exams/grading/[submissionId] → /teacher/homework/submissions
  实现：grading/[submissionId]/page.tsx

3.2 学生端

• /student/learning/assignments: 作业列表
  实现：page.tsx
• /student/learning/assignments/[assignmentId]: 作答页（开始/保存/提交）
  实现：[assignmentId]/page.tsx

---

4. 数据访问层（Data Access）

数据访问位于：data-access.ts

4.1 教师侧查询

• getHomeworkAssignments：作业列表（可按 creatorId/ids）
• getHomeworkAssignmentById：作业详情（含目标人数、提交数统计）
• getHomeworkSubmissions：提交列表（可按 assignmentId）
• getHomeworkSubmissionDetails：提交详情（题目内容 + 学生答案 + 分值/顺序）

4.2 学生侧查询

• getStudentHomeworkAssignments(studentId)：只返回“已派发给该学生、已发布、且到达 availableAt”的作业
• getStudentHomeworkTakeData(assignmentId, studentId)：进入作答页所需数据（assignment + 当前/最近 submission + 题目列表 + 已保存答案）

4.3 开发模式用户选择（Demo）

为了在未接入真实 Auth 的情况下可演示学生端页面，提供：

• getDemoStudentUser()：优先选取最早创建的 student；若无 student，则退化到任意用户

---

5. Server Actions

实现位于：actions.ts

5.1 教师侧

• createHomeworkAssignmentAction：从 exam 创建 assignment；可写入 targets；可选择 publish（默认 true）
• gradeHomeworkSubmissionAction：按题写入 score/feedback，并汇总写入 submission.score 与 status=graded

5.2 学生侧

• startHomeworkSubmissionAction：创建一次 submission（attemptNo + startedAt），并校验：
  • assignment 已发布
  • student 在 targets 中
  • availableAt 已到
  • 未超过 maxAttempts
• saveHomeworkAnswerAction：保存/更新某题答案（upsert 到 homework_answers）
• submitHomeworkAction：提交作业（校验 dueAt/lateDueAt/allowLate，写入 submittedAt/isLate/status=submitted）

---

6. UI 组件

6.1 教师批改视图

• HomeworkGradingView
  • 左侧：学生答案只读展示
  • 右侧：按题录入分数与反馈，并提交批改

6.2 学生作答视图

• HomeworkTakeView
  • Start：开始一次作答
  • Save：按题保存
  • Submit：提交（提交前会先保存当前题目答案）
  • 题型支持：text / judgment / single_choice / multiple_choice

题目 content 约定与题库一致：{ text, options?: [{ id, text, isCorrect? }] }（作答页仅消费 id/text）。

---

7. 类型定义

类型位于：types.ts

• 教师侧：HomeworkAssignmentListItem / HomeworkSubmissionDetails 等
• 学生侧：StudentHomeworkAssignmentListItem / StudentHomeworkTakeData 等

---

8. 校验

• npm run typecheck: 通过
• npm run lint: 0 errors（仓库其他位置存在 warnings，与本模块新增功能无直接关联）