docs: 提炼"聚合分子分母同一队列"检查方法（源自已合并 #58）

[linxi123-A]

背景

阶段十二：把一次已合并改动的经验变成下一位成员可直接照做的方法。

历史记录

引用已合并的 PR #58 （φ_grad 将未评分提交按 0 分计入导致梯度反转）：

• 触发 ：真实数据中存在Submission.score=None （已提交未评分），旧代码分子用if s.score 过滤 None、分母用len(half) 含 None，口径不一致；两半缺失率不同时梯度方向反转（[40,40,None,43] 进步被报成 φ_grad=0）。
• 处理 ：两半分别只收集score is not None 的提交，分子分母同一队列；任一半无评分时给中性默认 50。
• 验证 ：RED 3 failed/5 passed → GREEN 8 passed。
• 文档另记录了同源变体 refactor: session_lifecycle_payload 自查最近活动，删除 5 处重复调用 #67 ：一个分支处理两种语义（省略参数 vs 显式 None）引发 N+1，用 sentinel 区分。

交付物

新增方法文档 same-cohort-average-check.md ，含：

1. fix: φ_grad 将未评分提交按 0 分计入，导致进步梯度方向反转 #58 触发/处理/验证完整复盘；
2. 五步检查步骤 ：找聚合 → 写分子/分母两个集合 → 标口径差异 → 统一到同一队列 → RED→GREEN（构造缺失分布不均的输入）；
3. 适用场景清单。
   新例子验证方法 （AI 验收要求）：文档用学生首页平均分查询routes/main.py 的func.avg(Submission.score) 走完全部五步——SQLAVG 自动忽略 NULL，分子分母跳过同一批记录，口径天然一致， 判定：安全，无需修改 ；并给出危险对照写法（Python 侧sum(过滤)/len(未过滤) ）。这验证了方法既能抓出 fix: φ_grad 将未评分提交按 0 分计入，导致进步梯度方向反转 #58 的缺陷，也能正确放行安全代码，不会引导过度修改。

测试

Bash

运行

1

pytest tests/test_same_cohort_check_doc.py -q

• RED（文档创建前）：3 failed（FileNotFoundError）；
• GREEN： 3 passed ——核验文档引用 fix: φ_grad 将未评分提交按 0 分计入，导致进步梯度方向反转 #58 URL 与具体落点（maturity_calculator/phi_grad）、包含分子/分母/同一步骤要素、新例子 func.avg 有明确判定（安全 + AVG 忽略 NULL 理由）。
  相关子集：pytest tests/test_session_lifecycle.py tests/test_maturity_phi_grad.py -q → 23 passed 。

边界说明

• 纯文档 + 源码级测试，不改任何运行代码、接口、数据库与权限。
• docs/guides/ 受.gitignore 的docs/* （"keep the rest of docs internal by default"）约束，与仓库已跟踪的docs/ops-runs/ 、docs/superpowers/ 同样使用显式添加，不改变忽略策略本身。

回退

两个文件均为新增，revert/删除即可。

[XiaoCow666]

CodeSense 自动评审

核心目标已完成：新增了可执行的聚合口径检查文档及对应源码级校验，且未发现安全风险、运行回归或任务目标缺失。现有问题仅属于文档表达和测试鲁棒性方面的可选改进，不阻塞合并。

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

• 历史代码示例使用 if s.score，除了过滤 None 也会过滤合法的 0 分；文档当前主要强调 None，可补充这一点以避免读者误以为 truthy 过滤只影响空值。
• 文档测试主要通过关键词匹配验证内容，无法校验示例中的 SQL 语义或步骤完整性，后续可考虑增加更精确的结构化断言。
• “缺失时显式给中性结果”并不适用于所有聚合业务，建议补充说明中性值必须符合具体指标语义，或同时列出提前返回/显式标记不可用等选择。

已有验证信息

• PR 描述提供的证据为 pytest tests/test_same_cohort_check_doc.py -q GREEN：3 passed。
• PR 描述提供的相关子集证据为 pytest tests/test_session_lifecycle.py tests/test_maturity_phi_grad.py -q：23 passed。
• 本次审查未自行运行测试。

评审事件：a5e18d70-b699-11f1-8737-8c1e15f73d7f