# 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 以后。

## 开工前置命令

```bash
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 起。