Jyotisha/docs/tasks/TASK-upstream-sync2-fix-20260909.md

TASK · 上游同步二修复单（网页婚恋路径拿不到大运 / 围栏失败会打断报告）— 2026-09-09

• 基线：origin/staging @ 04ad3325（TASK-upstream-sync2-20260909 实现，已验收；TASK-report-chart-render-20260909 实现 2fdcb14f 同批在 staging）。
• 分支：codex/upstream-sync2-fix-20260909，worktree .worktrees/upstream-sync2-fix-20260909。
• 验收结论摘要（04ad3325）：定向 Python 176 通过；quick 门 708 通过 / 1 失败（test_shadbala_endpoint_returns_ranked_planet_strength，验收机缺 timezonefinder，环境缺口）；真实 pl9-export 时间系统表 5 + 10 行正确；api_server 11300 行（上限 11363）。前端（2fdcb14f）：tsc 0 错、lint 0 error、npm test 2991 / 2949 通过 / 28 失败（无 Docker 基线同 28）/ 14 跳过；next build --webpack / Static；globals.css gzip 35290 → 35630（+0.96%）。

1. 事故实证

P1 · 网页咨询路径的婚恋三层分类永远没有大运命中

在 04ad3325 起本地 API（scripts/jyotish_api_server.py --port 5299）对 /api/consultation_workflow（theme=marriage，虚构出生 1990-06-15 10:30 北京）实测：

观察	值
thematic_report.themes.marriage.evidence	D1-7th-house、Spouse-status-yoga、DK-UL-Dasha timing、Romantic-activation
Romantic-activation.details.hits	[]（只有 natal_structure: ["7H_Moon"]）
Relationship-formation / Legal-marriage	不出现
thematic_report.themes.marriage.timing.dasha_period	Saturn-Unknown
chart.modules.dasha 的键	current_md / remaining_years / total_years / start_date / periods / birth_balance / …，没有 maha_dasha / antar_dasha，也没有 vimshottari_analysis；current_md 是出生时大运（Rahu），不是当前
chart.modules.dasha_sub_periods.current	{"mahadasha": {"lord": "Saturn", …}, "antardasha": {"lord": "Jupiter", …}}（正确的当前 MD/AD）

链路：_thematic_dasha_info（L6555）只从 chart['dasha'] 与 dasha['vimshottari_analysis']['current'] 取 maha_dasha / antar_dasha；咨询路径 full_reading_used=false、dasha = full_modules.get('dasha')（L5425）是 chart 模块的 dasha，没有 vimshottari_analysis。于是传进 analyze_relationship 的 dasha_info 只有 current_md（出生 MD），MD_AD_KEYS = ('maha_dasha','mahadasha','antar_dasha','antardasha','bhukti') 一个都对不上 → event_class_split.*.hits 恒空。

后果：任务书 §2 的核心目标（按 MD/AD 把心动 / 成对 / 领证分开）在网页聊天路径上是空转，只剩本命结构观察；同时 report_orchestrator.py L701 那句「婚姻相关宫位与 karaka 将被激活，是缔结或调整伴侣关系的关键期」仍随 timing.dasha_period（Saturn-Unknown）无条件输出——这正是 BUG-608 要拆掉的合并式「婚恋机会」，只是换了个文件。

P2 · 围栏构造在 try 外，任何一张分盘出 ValueError 会让整份长报告 500

scripts/jyotish_engine.py _render_south_chart（L4226）：render_south_indian_chart 在 try 内，失败返回 _图盘生成失败_；但紧接的 build_chart_block(...) 在 try 外，resolve_chart_id / _sign_name 会 raise ValueError('chart id missing' / 'ascendant sign missing')。分盘 Ascendant 行的 sign 不在英文 12 星座内（例如引擎某分盘输出 sign_idx 而无 sign、或中文星座名）时，render_pl9_markdown 整体抛错，/api/reports/<id>/professional-reference 与 pl9-export 一起失败。22 张 golden 都是正常路径，没有覆盖这个分支。

P3 · /api/health 的 version 写死 6.9.14

scripts/jyotish_api_server.py L3402 'version': '6.9.14'（L7000 另一处 6.9.15），jyotish_vedic.__version__ 已是 6.9.16。健康检查报的 Skill 版本与实际不符（5d35731f 引入，非本轮回归，顺带修）。

2. 根因

• P1：_thematic_dasha_info 是为 /api/thematic_report 走 full reading 时写的，前提是 dasha 带 vimshottari_analysis；咨询路径 09-06 起改为复用 chart 模块后这个前提就没了，但当时只影响一句 legacy timing，没人发现。BUG-608 把 dasha_info 接上后，这条断链第一次有了产品后果。
• P2：任务书 §5 任务 1 写「失败路径不加围栏」，执行方理解为「SVG 失败不加」，没把围栏自身的失败纳入。
• P3：版本字符串散落三处，没有从 jyotish_vedic.__version__ 读。

3. 决策记录

决策	内容
D1	dasha_info 的当前 MD/AD/PD 一律从 chart.modules.dasha_sub_periods.current（_consultation_dasha_sub_periods L1432，按请求参考日切出）取；缺失时再回退 vimshottari_analysis；两者都缺时不从 dasha.periods 手算——日期只许来自引擎已切好的边界。
D2	report_orchestrator.py 婚恋主题的 activation_description 改为按 event_class_split 出句：有 legal_marriage MD/AD 命中才可写「缔结」；只有 romantic_activation 时写「感情被激活的观察期，不等于领证」；没有命中时不出「关键期」句，timing 保留日期但 activation_description 写「本期无婚恋事件类命中」。Saturn-Unknown 这种 AD 缺失时不得拼 -Unknown，改用 MD 单独显示。
D3	围栏失败只丢围栏、保留 SVG；不新增用户可见文案。
D4	三处版本字符串统一读 jyotish_vedic.__version__。

不推翻 TASK-upstream-sync2-20260909 任何红线。

4. 硬红线

1. scripts/jyotish_api_server.py 净增 ≤ 15 行（当前 11300，上限 11363）；_thematic_dasha_info 改动就地，不新增 handler。
2. /api/consultation_workflow 契约只增不改；thematic_report.themes.marriage.timing 现有键保留。
3. relationship_analysis.py / relationship_event_class_evidence.py 不改逻辑；P1 只修喂数。
4. 前端不动。

5. 任务分解

任务 1 · 喂正确的 MD/AD（P1）

• _thematic_dasha_info(chart, dasha)：先读 chart.get('modules', {}).get('dasha_sub_periods', {}).get('current')，映射 mahadasha.lord → maha_dasha、antardasha.lord → antar_dasha、pratyantardasha.lord → pratyantar_dasha（若存在）；再按原逻辑回退 vimshottari_analysis。
• 新测试 tests/test_thematic_dasha_info_source.py：构造 chart（含 dasha_sub_periods.current Saturn/Jupiter）与无 vimshottari_analysis 的 dasha → 返回 maha_dasha='Saturn', antar_dasha='Jupiter'；无 dasha_sub_periods 但有 vimshottari_analysis → 走回退；两者都无 → 不含 maha_dasha。
• 端到端：tests/test_relationship_event_class_evidence.py 加一条走 _derived_marriage_evidence 的用例，输入来自真实 /api/consultation_workflow 响应（把本轮实测的 1990-06-15 虚构盘响应存为 tests/golden/upstream_sync2/consultation_marriage_1990_fictional.json，只保留 chart.modules.dasha / dasha_sub_periods / planets / ascendant 与 thematic_report.themes.marriage），断言 Romantic-activation 或 Relationship-formation 至少一条 details.hits 非空（Saturn MD / Jupiter AD：Jupiter 为该盘 7L 或 DK 之一时命中；若该盘不命中，换一个命中的虚构出生并写明）。

验收：新测试绿；重跑本单 §1 的 curl，hits 非空、timing.dasha_period 不再含 Unknown。

任务 2 · 婚恋 activation 句按事件类出（P1 后半）

• scripts/report_orchestrator.py L701 附近：婚恋主题 activation_description 从 event_class_split 派生（见 D2）；dasha_period 在 AD 缺失时只写 MD。
• 测试：tests/test_report_orchestrator_marriage_timing.py（或就近既有文件）三例：仅 romantic → 含「不等于领证」；legal MD/AD 命中 → 可含「缔结」；无命中 → 不含「关键期」「缔结」。

验收：grep -n "缔结或调整伴侣关系的关键期" scripts/report_orchestrator.py 只在 legal 分支出现。

任务 3 · 围栏失败不打断报告（P2）

• _render_south_chart：build_chart_block 包 try/except Exception，失败返回 svg（不带围栏），并 logging.warning 一次（不含地名 / 用户串）。
• tests/test_report_chart_block.py 加一条：ascendant_row={'sign': '白羊'} 时 render_pl9_markdown 不抛、Markdown 含 <svg 且该处无 ```jyotish-chart。

任务 4 · 版本字符串（P3）

• L3402、L7000、L7120 三处改为 jyotish_vedic.__version__（fallback 后缀保留）；tests/test_api_server_security.py 或就近健康检查测试断言 version == __version__。

任务 5 · 记录

• docs/BUG_HISTORY.md：BUG-609（P1，关联 BUG-608、BUG-555 咨询复用 chart 模块）、BUG-610（P2，关联 BUG-607）、BUG-611（P3）。
• docs/tasks/PROGRESS-upstream-sync2-fix-20260909.md；CHANGELOG.md 一条（婚恋 activation 句按事件类出）。
• docs/testing/upstream-sync2-20260909.md 补一条：staging 上问「我什么时候会结婚」，回答里的大运名要与页面时间轴当前 MD/AD 一致，且不出现 Unknown。

6. 让步顺序

1. 任务 4（P3）。
2. 任务 2 的「AD 缺失只写 MD」可先只做 Unknown 不拼。
3. 不可砍：任务 1、任务 2 主体、任务 3、任务 5。

7. 开工前置命令

git -C /workspace/Jyotisha status -sb | head -1
git fetch origin --prune
git worktree add -b codex/upstream-sync2-fix-20260909 .worktrees/upstream-sync2-fix-20260909 origin/staging
cd .worktrees/upstream-sync2-fix-20260909
.venv/bin/python -m pytest tests/test_relationship_event_class_evidence.py tests/test_report_chart_block.py tests/test_consultation_workflow_domains.py -q   # 基线
.venv/bin/python scripts/jyotish_api_server.py --port 5299 &   # 复现 §1 的 curl

8. BUG 编号起点

docs/BUG_HISTORY.md 当前最大 BUG-608；本单 BUG-609 / 610 / 611，开工时重新核对。