Jyotisha/docs/tasks/TASK-report-reference-perf-fix-20261014.md

TASK · 长报告提速修复单（issue #61，第 1 次打回）

• 日期：2026-10-14
• 原任务书：docs/tasks/TASK-report-reference-perf-20261013.md
• 被验 SHA：69c739fbee3f5af6deed911482d82e49ed429bf7（codex/report-reference-perf-20261013）
• 执行方：Grok，同一分支续做（先 merge 最新 origin/staging，不改写已推历史）
• BUG 编号：沿用 BUG-1335、1336

1. 验收结论：本单自身全部通过；与 #60 合并后一条合同测试红

检查	结果	证据
与最新 staging 合并后的定向测试	未通过	tests/test_api_scratch_retention.py::test_new_scratch_local_dirs_are_registered_or_whitelisted：AssertionError: ['report_reference_cache']
逐字节一致（Claude 在 Linux、屏蔽 PyJHora 复跑 A/B）	通过	四张虚构盘 A / B 未命中 / B 命中 / 缓存首算的五个字段 sha 全部相同；format=json、edition=reference 两条 sha 相同
耗时	与回报一致	未命中中位数 21.1→15.6 s（day）等，降约 22–26%，未到 35% 门槛 → 渲染提速默认关正确；命中 0.02–0.03 s
缓存键含 today	通过	_high_rigor_birth_payload 在缺省时把当天日期写进 birth，跨天不会命中
GITHUB_SHA	通过	部署编排已传入；缺失或 unknown 时不缓存
jyotish_api_server.py	通过	零改动

根因：#60（BUG-1330～1332，已在 staging）新增了合同测试：scripts/ 里写 scratch/local/<子目录> 的地方，必须登记在 scripts/api_scratch_retention.py 的 REGISTRY（服务器周期清理）或 OFFLINE_SCRATCH_NAMES（自己会清理的缓存）里。本单新增的 scratch/local/report_reference_cache/ 两边都没登记。两单各自都对，合在一起才红——这不是你的疏漏，是两单同时在做。

2. 修法要求

1. 合并最新 origin/staging（含 #60）。
2. 在 scripts/api_scratch_retention.py::OFFLINE_SCRATCH_NAMES 加 "report_reference_cache"，旁边写一行注释：它与 consult_full_data_cache 同走 consult_full_data_cache.get_or_build，每次调用先 prune_cache(name=…) 删两天前的文件，自己会清；含出生资料，保留期 2 天。
3. 不改两个模块的任何逻辑。
4. PROGRESS 末尾记一行。

3. 验收标准

• python -m pytest tests/test_api_scratch_retention.py tests/test_report_reference_perf.py tests/test_consult_card_full_source.py -q 全绿；
• Claude 全量 pytest 与 staging 基线逐条比对无新增。

4. 让步顺序

无。第 1 次打回。