From b91177672591b64b2b7eaf30c1d29471acaa7b3b Mon Sep 17 00:00:00 2001
From: chenyuan <chenyuan@example.com>
Date: Mon, 3 Aug 2026 09:32:50 +0800
Subject: [PATCH] docs: specify comprehensive training module

---
 ...03-comprehensive-training-module-design.md | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-03-comprehensive-training-module-design.md

diff --git a/docs/superpowers/specs/2026-08-03-comprehensive-training-module-design.md b/docs/superpowers/specs/2026-08-03-comprehensive-training-module-design.md
new file mode 100644
index 0000000..7817963
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-03-comprehensive-training-module-design.md
@@ -0,0 +1,43 @@
+# 综合实训模块设计
+
+## 目标
+
+在现有五个互联网产品开发实训模块之外，增加顶部独立的“综合实训”模块。它用于老师后续配置一个贯穿完整案例的综合任务或考试，并由现有任务分配功能控制学生端是否可见。
+
+## 范围
+
+- 新增固定内置任务：`comprehensive-case-training`，默认名称为“综合案例实训”，所属项目为“综合实训”。
+- 该任务复用现有班级任务配置能力：老师可为自己的教学班修改任务名称、案例资料、背景、目标、要求和步骤。
+- 该任务进入现有任务分配列表；老师发布后，学生端才可看到并进入该任务。
+- 学生端通过通用实训页承载该任务，不新增专用表单页面。
+- “综合实训”在教师任务管理顶部项目筛选、学生侧导航、学生实验报告和成绩计算中作为第六模块显示。
+
+## 发布与可见性
+
+`TaskAllocation` 继续按任务键控制发布状态。默认综合案例任务不发布：
+
+1. 未发布时，学生任务列表和学生导航不显示该任务。
+2. 已发布时，学生可访问该任务并提交答案，教师可通过现有任务配置编辑案例内容。
+3. 恢复班级默认任务只删除该班级的任务内容覆盖，不改变任务分配状态，保持与现有任务一致。
+
+## 成绩规则
+
+- 综合实训权重固定为 20%。其余五个模块继续使用 10%、30%、10%、10%、20%。
+- 仅当综合案例任务已发布且该教学班存在至少一个启用的综合实训任务时，综合实训模块参与总成绩计算。
+- 未发布或没有综合实训任务时，综合实训不计入总分；其余已参与模块的权重按比例归一化为 100%，避免因老师尚未布置综合案例而降低学生成绩。
+- 已发布时，综合实训模块分数为该模块所有已启用、已发布任务 AI 评分的平均分，再以 20%权重计入总分。
+- 学生实验报告仍展示六个模块；未发布的综合实训显示“未布置”，任务数为 0，不将其作为 0 分扣减。
+
+## 数据与兼容性
+
+- `training_task` 和 `training_task_class_config` 不新增字段，复用 `task_key`、`project_name` 和既有任务内容字段。
+- 启动时的内置任务补齐逻辑必须将综合案例任务写入已有数据库和所有教学班任务配置。
+- 既有五模块任务、既有班级配置和任务分配数据保持不变。
+- 前端路由继续使用通用实训页，新增任务键映射到该页面；页面保持使用学生身份下的任务详情接口，以读取该班级覆盖内容。
+
+## 错误处理与验收
+
+- 非班级创建老师不能编辑综合案例任务，也不能创建学生演示会话或发布其他老师的任务。
+- 未发布时，学生直接访问综合任务路由应得到“任务未配置”结果，且不暴露案例资料。
+- 发布后，学生端显示任务、案例资料和动态步骤；提交后的 AI 分数进入综合实训模块统计。
+- 需要覆盖内置任务回填、默认未发布、发布后的学生可见性、未布置时的总分归一化、发布后的 20%计分，以及前端构建。