diff --git a/docs/superpowers/specs/2026-07-30-training-task-restore-default-design.md b/docs/superpowers/specs/2026-07-30-training-task-restore-default-design.md new file mode 100644 index 0000000..2aab69e --- /dev/null +++ b/docs/superpowers/specs/2026-07-30-training-task-restore-default-design.md @@ -0,0 +1,61 @@ +# 教学班实训任务恢复默认内容设计 + +## 背景与现状 + +教师端“实训任务”页面按教师本人创建的教学班进行编辑。任务内容写入 +`training_task_class_config`,以 `(teaching_class_id, task_key)` 为唯一键。 + +读取任务时,系统先读取平台默认任务 `training_task`,再合并该教学班的内容覆盖。因此, +教师对某个教学班的编辑只影响该班及其学生,不会影响同一教师创建的其他教学班,也不会影响 +其他教师的班级。 + +学校“默认实训任务配置”中的启用/停用开关保存于 `task_allocation`,仅决定任务是否可用; +它与本次的任务内容恢复互不替代。 + +## 目标 + +让教师可以撤销自己对教学班实训任务内容的编辑,重新使用平台默认实训任务内容。 + +提供两个恢复范围: + +1. 当前教学班的单个任务; +2. 当前教学班的全部任务。 + +## 不变的边界 + +- 恢复操作只针对当前教师本人创建的教学班,沿用现有 `requireOwnedTeachingClass` 鉴权。 +- 恢复不会修改 `training_task` 平台默认内容。 +- 恢复不会修改 `task_allocation` 的学校默认配置或教学班启用/停用配置。 +- 恢复不会删除学生完成记录、上传材料、得分、进度或其他业务数据。 +- 不会影响任何其他教学班。 + +## 后端设计 + +在 `TrainingTaskController` 与 `TrainingTaskService` 增加两个接口: + +| 操作 | 方法与地址 | 行为 | +| --- | --- | --- | +| 恢复单个任务 | `DELETE /api/training-tasks/classes/{teachingClassId}/{taskKey}/override` | 删除当前班级该 `task_key` 的 `training_task_class_config` 记录。 | +| 恢复全班任务 | `DELETE /api/training-tasks/classes/{teachingClassId}/overrides` | 删除当前班级全部 `training_task_class_config` 记录。 | + +两个接口均先校验该教学班归当前登录教师所有。删除覆盖记录后,现有 +`listForTeachingClass`、学生端任务详情和学生端任务列表无需改变:它们会自然回退到 +`training_task` 的默认内容。 + +删除不存在的覆盖记录视为幂等成功,便于重复点击、刷新重试,以及恢复后再次调用。 + +## 前端交互 + +页面仅在已选中教学班时展示恢复入口: + +1. 编辑抽屉底部新增危险操作按钮“恢复此任务默认内容”。点击后显示二次确认,确认后调用单任务接口、关闭抽屉并刷新任务列表。 +2. 教学班筛选区新增“恢复本班全部默认任务”按钮。点击后显示明确提示:仅恢复当前所选教学班的任务内容,不影响学生成绩、完成数据和其他班级。确认后调用全量接口并刷新列表。 +3. 未选中教学班时不展示恢复操作;默认任务预览模式保持只读。 + +## 验收标准 + +1. 教师编辑 A 教学班任务后,A 班学生读取到编辑内容,B 班仍读取其自身内容或平台默认内容。 +2. 恢复 A 班单个任务后,该任务立即显示并读取平台默认内容;A 班其他任务不变。 +3. 恢复 A 班全部任务后,该班所有任务均显示并读取平台默认内容。 +4. 恢复操作不改变任务启用状态分配,不删除学生完成、得分或进度数据。 +5. 非该班创建者调用接口被拒绝。