From 16436042d744ff763714180c691ecc94dcd3765b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=99=88=E6=B2=85?= <907037276@qq.com>
Date: Thu, 3 Sep 2026 14:09:53 +0800
Subject: [PATCH] docs: specify teacher grade progress sync

---
 ...026-09-03-teacher-grade-progress-design.md | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-09-03-teacher-grade-progress-design.md

diff --git a/docs/superpowers/specs/2026-09-03-teacher-grade-progress-design.md b/docs/superpowers/specs/2026-09-03-teacher-grade-progress-design.md
new file mode 100644
index 0000000..590f346
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-03-teacher-grade-progress-design.md
@@ -0,0 +1,48 @@
+# 教师成绩列表进度与评分同步设计
+
+## 目标
+
+教师端成绩列表展示学生已完成实训任务数与总实训任务数，并实时汇总教师在任务评阅中保存的逐任务评分；成绩列表不再允许直接录入或保存教师总分。
+
+## 问题与根因
+
+当前进度统计从旧的 `stu_grade` 查询已完成模块，而当前实训完成状态保存在 `student_training_answer`，导致完成实训的学生仍显示为 `0%`。当前教师评分写入单独的 `teaching_class_teacher_score` 汇总表，和逐任务评阅没有数据关联。
+
+## 数据模型
+
+在 `student_training_answer` 增加以下字段：
+
+- `teacher_score`：教师对该任务的 0–100 分评分，可为空。
+- `teacher_scored_by`：评分教师用户 ID，可为空。
+- `teacher_scored_at`：评分时间，可为空。
+
+每条答卷已经唯一对应学生、教学班与实训任务，因此不新增独立评分表，也不再使用人工汇总评分作为成绩列表的数据源。
+
+## 评阅与权限
+
+成绩详情弹窗扩展为任务评阅界面，展示当前教学班已启用的全部任务及对应任务状态、AI 评测成绩和教师评分。班级创建教师可对已提交或状态为 `COMPLETED` 的任务录入 0–100 分并保存；其他教师仅可查看。未完成任务不可评分。
+
+成绩列表的“老师评分”列只读：尚无任何教师任务评分时显示“待评阅”，存在评分后显示实时计算结果。移除列表中的数字输入框、保存按钮和人工汇总评分接口调用。
+
+## 实训进度
+
+总任务数取当前教学班启用的已分配任务（使用学校默认任务回退规则，排除发布标记与未参与的综合实训）。完成任务数取同一学生、同一教学班中 `submitted = true` 或 `progress_status = COMPLETED` 的答卷，并按任务去重。
+
+列表显示 `已完成数/总数`，并保留百分比提示；没有可用任务时显示 `--`。
+
+## 教师评分计算
+
+教师总分复用当前参考成绩的六模块算法：按 `TrainingTask.projectName` 把任务归入六个模块；每个模块先计算该模块所有已分配任务教师评分的平均值，未评分任务按 0 分参与平均；再乘以当前教学班的六项权重。综合实训是否参与、参与权重归一化与 `ScoreRankServiceImpl.calculateSixModuleScore` 保持一致。
+
+该值在成绩列表和导出查询时即时计算，不依赖“成绩更新”按钮。任务评分保存后，重新请求列表即可得到新总分。
+
+## 接口与兼容性
+
+- 成绩详情接口改为返回全部有效任务及答卷、AI 分数和教师评分。
+- 新增受班级创建教师权限保护的逐任务评分保存接口。
+- 现有 `/api/weight/saveTeacherScore` 不再由前端调用；旧汇总数据保留，不迁移、不删除。
+
+## 测试
+
+- 后端：验证答卷完成状态统计、无任务显示空进度、逐任务评分权限、未完成任务不能评分、按六模块权重汇总及未评分任务按零分计算。
+- 前端：验证列表展示完成数/总数、教师评分只读、详情中存在任务评分控件、没有列表人工评分控件或人工评分 API 调用。