docs: design training task default restore

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. 非该班创建者调用接口被拒绝。