Jyotisha/docs/tasks/TASK-annual-return-frame-20261003.md

TASK：太阳返照时刻对齐（出生太阳同参考系 + 保留秒）— 2026-10-03

基线与串行

• 必须在第三批（TASK-astrologer-rulings-batch3-20261003，分支 codex/astrologer-rulings-batch3-20261003）合入 staging 之后开工。 两边都改 scripts/solar_return.py，第三批 T1 还改了年运下游。
• 以合入后的 origin/staging 为基线。分支 codex/annual-return-frame-20261003，工作树 .worktrees/annual-return-frame-20261003。
• 依据：docs/research/shared_engine_reuse_audit_2026_10_03.md §S1。
• 上游参照：/workspace/yinduzhanxing 的 7cc6425d（出生太阳改在求解器同一参考系重算）和 46ed9399（年盘保留秒）。只读，不提交、不推送上游。

事故实证（按符号定位）

1. 目标经度和求解器不在同一参考系。
   • scripts/solar_return.py:calc_solar_return_chart 里，birth_sun_lon = sun_data.get('degree_raw', …) 取自 jyotish_engine.compute_chart_data 的出生太阳。
   • _find_solar_return_swe 用 _get_sun_lon_jd（swe.calc_ut + sidereal_flags）逐步逼近。
   • 标准盘（1963-08-07 21:15 IST Sambalpur，Lahiri）两者相差 15.1″，2025 年返照时刻差 6 分 16 秒（网站 18:24:47，上游 18:31:03）。
2. 年盘丢秒。 同一函数用 sr_hour_int, sr_minute_int 调 compute_chart_data，没传 second，年盘时刻截到整分钟。
3. 外部复核。 PyJHora drik.next_solar_date 在 5 个样本年与「同参考系 + 保留秒」相差 0.0 分钟，与现状相差 −7.2～+6.8 分钟。
4. 影响面。 9 位公开名人（tests/test_pancha_mahapurusha_main_detector.py:FIGURES）× 2000–2026 年 = 243 张年盘：
   • 年盘上升星座变 13 张（5.3%）；
   • 年主变 11 张（4.5%）；
   • 昼夜判定变 0 张。

根因

网站引擎从上游同步到 f2241463（2026-09-03）后，solar_return.py 只按 BUG 单补过本地化与返照地点（41d1c740）。上游 9 月 7–8 日的两处修正没进来。与 ERR-109「同步太阳返照只核对函数在不在」同类。

决策记录

• 返照的定义是「太阳回到出生时的恒星黄经」。出生和返照必须用同一参考系计算，这不是方法分歧，而是计算错误。产品负责人 2026-10-03 晚确认：按上游 7cc6425d / 46ed9399 的做法修，第三批合入 staging 后开工，由 Claude 直接执行。
• 只搬这两处。上游同期加的 position_mode、solar_return_time_offset_seconds、node_longitude_offset_arcseconds、annual_house_system_for_sahams 参数不搬（产品不用，属研究回放参数）。
• 本地化（_localize_return_datetime、annual_location）保留网站现有实现，不回退成上游的 birth_tz。

硬红线

1. 不改冻结身份里的文件（references/rectification_sealed_holdout.v1.json → production_scoring_files）。solar_return.py、tajika.py 不在清单内；v5 77 例必须与改动前逐项相同（校正不用年盘，跑一遍证明）。
2. 不改普通对话提示词，不动迁移，不升打分版本。
3. PyJHora（AGPL）只能作为外部对照：只允许把它算出的返照 JD 数字写进 golden，不得 import 进产品代码或测试运行路径。
4. 改到 references/*.json 的字符串要有 _en 对照；tests/test_report_english_dictionary.py 单独跑。
5. 禁止 git stash。开工前 df -h /，少于 15G 停下。

任务分解

T1 出生太阳与求解器同参考系

• 在 calc_solar_return_chart 中改为 birth_sun_lon = _get_sun_lon_jd(birth_jd_ut, ayanamsa_name=ayanamsa_name)；拿不到时才退回出生盘的 degree_raw。行文照上游 7cc6425d。
• solar_return 返回值加 target_sun_frame: "swe_sidereal_flags"，便于日后核对。
• 验收：
  • 新测试：标准盘 2025 年返照 JD 与 PyJHora 参照值（预先算好写死在 fixture，注明来源 pyjhora drik.next_solar_date）相差 ≤ 0.5 分钟；
  • 另取乔布斯 2012、齐达内 2002 两例同样断言。

T2 年盘保留秒

• 调 compute_chart_data 时传 second=sr_dt_ut.second，去掉 sr_hour_int / sr_minute_int 的截断。照上游 46ed9399。
• 验收： 新测试断言年盘 jd 与返照 jd_ut 相差 < 1 秒。

T3 下游与 golden

• 用真实引擎重采受影响的 golden：
  • frontend/tests/fixtures/consult-evidence-card-golden.json；
  • 报告与年运包相关 golden（以 grep -rl "solar_return\|varshesha\|mudda" tests frontend/tests 实测为准）。
• 每个改动的断言写「原值 / 新值 / 原因」三栏。
• 验收：
  • 进度记录附 243 张年盘前后对比表：年盘上升、昼夜、年主、Mudda 首运星（第三批后 Mudda 首运星不随年盘变，应 0 变化，作为回归证据）；
  • 历史报告能打开（旧报告存的是生成时的结果，不重算）。

T4 记录

• docs/BUG_HISTORY.md 新条目：现象、根因（两处）、修复、验证（PyJHora 对照、243 张影响表）、防复发（同参考系测试 + 同步清单加「返照求解参考系」一行），关联 ERR-109、BUG-1026～1028。
• docs/research/pre_work_error_ledger.md 在 ERR-109 下补一行复发说明。
• CHANGELOG.md（用户可感知：约 5% 的年份年盘上升和年主会变）；PROGRESS-annual-return-frame-20261003.md；docs/tasks/README.md 改状态。

让步顺序

T1 → T2 → T4 → T3。T1 的 PyJHora 对照不过（> 0.5 分钟）时停下回报，不做 T2 以后。

开工前置命令

cd /workspace/Jyotisha && git status -sb | head -1
git fetch origin --prune
git log --oneline origin/staging | grep -m1 "BUG-1218"   # 确认第三批已合入，否则不开工
git worktree add -b codex/annual-return-frame-20261003 .worktrees/annual-return-frame-20261003 origin/staging
df -h /
grep -oE "BUG-1[0-9]{3}" docs/BUG_HISTORY.md | sort -u | tail -1
git -C /workspace/yinduzhanxing show 7cc6425d -- scripts/solar_return.py
git -C /workspace/yinduzhanxing show 46ed9399 -- scripts/solar_return.py
python3 scripts/pre_work_check.py --remote-timeout 8 --command-timeout 45

验收口径

• Python 定向测试；run_quality_gate.py --profile quick；另跑 tests/test_report_english_dictionary.py。
• v5 逐项相同。
• 前端：tsc 0 错；lint 0 error；npm test 失败名单与开工基线逐条相同。
• 不 push，由 Claude 验收后推 staging。部署后 /api/health 的 gitCommit 等于含门禁改动的提交。

BUG 编号起点

开工时核对当前最大号。第三批计划用到 BUG-1216 起若干条，本单预计从 BUG-1220 起。