fix+docs: 带新手走检查流程——修提交历史页口径，文档补业务核实步骤

[linxi123-A]

背景

阶段十三：带别人走一遍流程。让无项目背景的成员（AI 扮演）按已合并的方法文档 #68 独立执行一次聚合检查，记录卡点，修改说明并复现。

第一轮执行记录

任务 ：新手仅读方法文档 + 目标代码（ assignments.py L1405-1409 ），按五步检查学生提交历史页的平均分。

新手判定：危险 ——方向正确，但论证是拿文档 §1 的 #58 缺陷模式 机械对号入座 ，没有（也未被指导要）核实业务口径。若换成"有意把未评分按 0 计"的场景，同样推理会产出误报。

记录到的卡点 ：

1. 文档没教"判定前先核实指标业务定义"，模式匹配与业务证据的优先级不清；
2. 中性默认值 50（§1）vs 0（§3 例子）的选择无规则，新手不知道修复时用哪个；
3. 新手附带发现真实边界 bug：全未评分时best_score 泄漏 None，模板%.1f 格式化会出错。

带教事实核查

核实同一指标在系统内的全部计算点：

位置 口径 assignments.py L546（教师详情） if s.score is not None 排除未评分 assignments.py L588（学生视图） 同上 tasks/submission_tasks.py L63-75（官方统计） status=="evaluated" +score.isnot(None) assignments.py L1407（提交历史页，改前） sum(s.score or 0) / len(全部) ，把未评分当 0——孤立不一致

三处对照口径一致排除未评分，无证据表明 L1407 是有意口径 → 确认真实缺陷 + best_score None 泄漏。

改动前后差异

代码 ：

• 新增 submission_stats.py ：纯函数submission_score_stats ，分子/分母/最高分只取已评分提交，无数据返回(0, 0) ，真实 0 分正常参与。
• assignments.py L1406-1411 ：删除or 0 聚合与 best_submission 局部变量，改为调用纯函数，口径与全系统对齐。
  Python

1
2
3
4
5
6
7

`# 改前
average_score = sum(s.score or 0 for s in submissions) / total_submissions if total_submissions > 0 else 0
best_submission = max(submissions, key=lambda s: s.score or 0) if submissions else None
best_score = best_submission.score if best_submission else 0

改后

average_score, best_score = submission_score_stats(submissions)`

说明文档 （ same-cohort-average-check.md ）：

• 步骤 2 增加"标出集合内部的值转换（or 0/coalesce）"；
• 步骤 3 改为" 先核实业务定义、找对照口径 ，再标口径差异"，并写明"模式只是线索，业务口径证据才是依据"；
• 新增 §3 默认值选择规则（评分公式内用中性 50、展示层用 0、计数用 0）及关键区分"无数据回退 0 ≠ 把缺失当 0 分计算"；
• 新增 §5 本次带教案例。

改动后的复现结果

第二轮执行 ：另一名无上下文新手按 升级后 文档检查修复后代码：

• 主动建立三处对照口径证据链，判定 安全 ，依据是业务证据而非模式外形；
• 正确放行两个易误报点（total_submissions 含未评分是独立计数、纯函数缺status=="evaluated" 与同文件路由点一致）；
• 明确反馈：文档指引清晰无矛盾，"先核实业务定义"实质改变了其执行方式；第一轮三个卡点全部消除。
  测试 （实际输出）：

Bash

运行

1
2

pytest tests/test_submission_stats.py tests/test_same_cohort_check_doc.py tests/test_assignment_knowledge_views.py -q → 20 passed

• 新增 test_submission_stats.py 5 用例：[40,40,None,43] →41/43、全未评分→0/0（修复前 None 泄漏）、空列表→0/0、正常路径 70/80、真实 0 分[0,80] →40/80；
• 文档测试新增 1 项守护本次升级（业务定义/对照口径/孤立替换/中性/submission_score_stats/复现结果）。

未验证范围

• 未起 Flask 做页面级验证；纯函数与文档为源码级验证。
• 未跑全量（无后端结构变更，影响面限一个视图的统计块）。
• 历史正式库数据未涉及。

回退

单提交，revert 即可恢复旧口径与旧文档。

[XiaoCow666]

CodeSense 自动评审

核心修复已完成：提交历史页现在只按已评分提交计算平均分和最高分，并处理全未评分时的默认值，避免未评分被当作 0 分及 None 泄漏。文档、纯函数测试和回归用例均已补充，未发现需要阻塞合并的问题。

合并后可以继续改进的地方

• 尚未进行 Flask 页面级验证和全量测试，当前验证主要覆盖纯函数、文档约束及相关测试集合。
• submission_score_stats 的类型注解将平均分固定标为 float、最高分固定标为 int；若底层 score 使用 Decimal 或其他数值类型，注解与实际返回类型可能不完全一致，但不影响当前逻辑。

已有验证信息

• PR 描述报告执行 pytest tests/test_submission_stats.py tests/test_same_cohort_check_doc.py tests/test_assignment_knowledge_views.py -q，结果为 20 passed。
• 新增 5 个纯函数用例覆盖混合未评分、全未评分、空列表、正常路径和真实 0 分。
• PR 描述明确记录未验证 Flask 页面级行为，也未运行全量测试。

评审事件：30661860-b750-11f1-985f-d97ee8b5e241