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 次打回。