diff --git a/docs/superpowers/specs/2026-08-01-teacher-score-scope-design.md b/docs/superpowers/specs/2026-08-01-teacher-score-scope-design.md new file mode 100644 index 0000000..f3c8e7e --- /dev/null +++ b/docs/superpowers/specs/2026-08-01-teacher-score-scope-design.md @@ -0,0 +1,65 @@ +# 教师端成绩中心:教学班范围与六模块权重设计 + +## 背景 + +系统已切换为教师创建并维护教学班。教师端成绩中心仍按学校范围读取成绩、首页图表接口可回退到学校聚合,且旧成绩权重模型只有五个历史项目。这会使教师看到或操作其他教师班级的成绩,也无法按当前实训任务项目计算成绩。 + +## 目标 + +1. 教师只能读取、导出、查看详情及更新自己创建的教学班成绩。 +2. 教师首页的班级平均分走势、成绩分布饼图和最高/最低/平均分只统计该教师名下教学班。 +3. 成绩权重以教学班为单位配置,互不影响;按当前六个实训项目计算总成绩。 + +## 授权与数据范围 + +- 有效教学班必须同时满足:`class_type = TEACHING`、`school_id` 与当前教师一致、`created_by` 等于当前教师用户 ID。 +- 后端从登录上下文取得教师身份和用户 ID,不信任前端提交的 `operatorId`、`classId` 或 `schoolId`。 +- 未传班级时,成绩列表、导出及首页聚合均限制在该教师全部自有教学班;教师没有教学班时返回空结果或零统计。 +- 传入非本人教学班、旧行政班或跨学校班级时,后端返回无权限,不泄露是否存在该班级或其中学生。 +- 成绩详情必须同时验证学生属于请求的自有教学班。 +- 成绩更新必须指定并验证自有教学班,禁止使用“全校更新”的回退路径。 + +## 首页与成绩中心 + +### 成绩中心 + +- 班级下拉仅加载当前教师自有教学班。 +- 查询、导出、详情和成绩更新请求携带当前用户标识,服务端再次按自有教学班过滤。 +- 学生范围从教学班成员关系取得;成绩、实训进度及详情均以该教学班维度读取。 + +### 教师首页 + +- 平均成绩走势按当前教师自有教学班分别形成曲线。 +- 成绩统计只能选择自有教学班;未选择时汇总当前教师全部自有教学班,不再按学校全量数据统计。 +- 服务端为走势与统计接口增加教师身份校验和教学班成员过滤,前端下拉仅作体验层限制。 + +## 六模块权重 + +权重配置按 `teaching_class_id` 存储。首次访问某教学班时生成以下默认值,总和必须为 100%: + +| 项目 | 权重 | +| --- | ---: | +| 互联网产品开发基础认知 | 10% | +| 市场洞察与需求分析 | 30% | +| 产品规划与设计 | 10% | +| 产品开发与测试验证 | 10% | +| 产品上线与运营推广 | 20% | +| 综合实训 | 20% | + +- 权重弹窗必须先选择教学班;读取和保存均验证班级所有权。 +- 总成绩按教学班启用任务分组:同一项目内对已评测任务取平均分,再乘该项目权重;未评测任务按零分计入项目平均,未启用项目不参与平均但其权重仍保留在配置中。 +- 现有学校级五项 `weight` 记录仅作为旧成绩数据兼容来源;教师端新教学班成绩计算不再读取或修改它,避免一个教师修改全校成绩口径。 + +## 数据与兼容策略 + +- 新增教学班维度的六模块权重表(唯一键为教学班 ID),并提供幂等建表/初始化迁移。 +- 成绩聚合读取当前的实训任务配置、学生作答与 AI 评测分数;旧 `stu_rank` 记录不作为新教学班总分的唯一来源。 +- 历史学校级五模块数据保留,旧接口及学生端不在本需求内改变;教师端新增/调整的接口返回六模块聚合结果。 + +## 验收 + +1. 甲教师不能通过页面、接口参数或导出请求读取乙教师教学班成绩。 +2. 甲教师首页趋势和统计均不包含乙教师教学班数据。 +3. 权重设置只显示六个指定模块,默认值为 10/30/10/10/20/20,校验总和为 100%。 +4. 甲教师修改某班权重后,只影响该班成绩重算,不影响甲的其他班或乙的班级。 +5. 无自有教学班的教师看到空列表、空趋势和零统计,且无法发起全校成绩更新。