docs(report): add blocked-repairs task brief — varga shape, transit receipt, karakas layer
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr
This commit is contained in:
Jesse_Chen
@@ -0,0 +1,171 @@
|
||||
# 任务书 · 个人报告全主题 blocked 修复（2026-09-02）
|
||||
|
||||
基线：`origin/staging` @ `24a1cf37`。
|
||||
|
||||
## 事故实证
|
||||
|
||||
2026-09-02 15:45 staging 真实生成的 personal_full 报告（请求主题 career/marriage/timing/wealth）四个主题**全部 blocked**，摘要退化为"报告主题尚未生成"。blocked 理由：
|
||||
|
||||
- career：缺少最低证据组 AmK、Transit
|
||||
- marriage：缺少最低证据组 DK
|
||||
- timing：缺少最低证据组 Transit
|
||||
- wealth：缺少结构化分盘 D2、D11
|
||||
|
||||
已在本地用 `origin/staging @ 24a1cf37` 的前端提取层 + 同版本 Python 引擎（`scripts/jyotish_api_server.py`，虚构 smoke 出生数据，按 worker 的方式每主题一次 `/api/consultation_workflow`）**完整复现**：blocked 主题与理由逐字一致。这是确定性缺陷，不是线上环境问题。
|
||||
|
||||
## 根因（已逐项定位，不需要重新猜）
|
||||
|
||||
**根因 1（wealth）：分盘值形状不匹配，所有分盘图提取失败。**
|
||||
引擎 `chart.modules.varga_full` 的值形状是：
|
||||
|
||||
```json
|
||||
{ "ascendant": { "sign": "Gemini", "sign_index": 2, "degree": 21.027 },
|
||||
"planets": { "Sun": { "sign": "Libra", "sign_index": 6, "degree": 15.23, "house": 5 }, ... },
|
||||
"house_chart": [["Ketu"], [], ...], "division": ..., "name": ..., "meaning": ... }
|
||||
```
|
||||
|
||||
而 `frontend/src/lib/personal-report-generation.ts` 的 `deriveVargaHousesFromEngine`（约 :336）读的是**大写 `Ascendant` + `sign_idx` + 顶层行星键** → 每张分盘都返回 null → bundle `charts` 只剩 D1。昨日 `45f190a1` 修了键名别名（`D2_Hora`→`D2`）并新增"claim card 主题缺结构化分盘图则降 blocked"的兜底（`demoteThemesMissingRequiredCharts`），但没修值形状——于是 wealth 从"write 后文档校验失败"变成"bundle 层 blocked"。`643f6f7a` 的 fixture 是按**旧形状手造**的，所以测试全绿、线上照挂。（2026-08-30 观察到的 `final_parse_rejected` 大概率同源。）
|
||||
|
||||
**根因 2（timing、career 之一半）：Transit 回执从不生成。**
|
||||
引擎响应 `chart.modules.transits` 存在且 `status: "executed"`（含 sade_sati、triggers、search_period、boundary），但 `consumer_context.available_layers` 与 machine packet sections 里都没有 transit 名目，前端提取层从不为它 upsert 执行回执 → 要求 Transit 的 timing/career 自这套 claim gate 上线起从未通过。存量问题。
|
||||
|
||||
**根因 3（career:AmK、marriage:DK）：consultation 响应没有 Chara Karaka 数据。**
|
||||
整个响应中无 Amatyakaraka/Darakaraka 数值层：`chart.modules.jaimini` 只有 `arudha_padas`；guided topics 里 DK 的值是空占位符 `- H-`。引擎的 full-reading 路径有现成 karaka 计算（`scripts/jaimini.py`），但 `scripts/jyotish_api_server.py` 的 `_attach_local_consultation_layers` 没有把这层挂进 consultation 响应。**前端修不了，必须引擎响应新增字段。**
|
||||
|
||||
## 决策记录
|
||||
|
||||
产品负责人 2026-09-02 确认修复方向并授权：
|
||||
|
||||
- **(a)** 引擎侧允许在 consultation 响应中**新增** Chara Karaka 字段（这是 `TASK-report-skill-parity-20260901.md` 任务 0 预留的"响应新增字段"止损分支，正式启用）。仍然只许新增、不许改动既有字段的键名、形状或语义。
|
||||
- **(b)** `643f6f7a` / 既有测试中按旧分盘形状手造的 fixture 与断言，属于"锁住本轮要修的缺陷本身"，允许按红线 9 的程序修改（注明原值与原因）。
|
||||
- **(c)** 主题最低证据组（`report-theme-evidence-plan.ts`）**不在授权范围内**：不得为了让主题通过而删除或放宽 AmK/DK/Transit/D2/D11 要求。修法只能是把证据真实供给上。
|
||||
|
||||
## 硬红线
|
||||
|
||||
1. **最低证据组一条不得放宽**（见决策记录 c）。`demoteThemesMissingRequiredCharts` 兜底保留，不得删除——修好值形状后它自然不触发。
|
||||
2. **引擎改动只许响应新增字段**：不改既有字段、不改排盘算法、不改 full-reading 路径；新增层必须复用 `scripts/jaimini.py` 既有实现，不得重写 karaka 算法。
|
||||
3. **fixture 必须来自真实引擎响应**（golden），不得再手造形状。任务 0 是门控：先落 golden fixture 与形状契约测试，任务 1–3 的实现测试必须建立在它之上。
|
||||
4. 上一轮任务书（`TASK-report-skill-parity-20260901.md`）的红线继续有效：输入隔离不放松、writer 输出 schema 只可收紧、`assertionLevel` 推导与 consensus ≥2 verified 防升级校验一字不改、本轮不改数据库结构、章节串行、telemetry 只记指标名与数值。
|
||||
5. 隐私红线：fixture 与测试只用虚构 smoke 出生数据；golden fixture 入库前确认不含任何真实用户资料。
|
||||
6. 推 staging 前 `./node_modules/.bin/tsc --noEmit` 必须通过（**不要用 `npx tsc`**，会装到空包 `tsc@2.0.4`）。不得改 `.gitea/workflows/**`，不得自行提升 main。
|
||||
7. Python 侧改动必须带单元测试（`.venv` + unittest/pytest，按仓内既有测试形式），并真实跑过。
|
||||
|
||||
让步顺序：数据不损坏 > 证据纪律不回退 > 功能与测试不回归 > 可验证的修复 > 成本 > 代码整洁。
|
||||
|
||||
## 开工前置
|
||||
|
||||
```bash
|
||||
git fetch origin --prune
|
||||
git worktree add -b codex/report-blocked-repairs-20260902 \
|
||||
../.worktrees/report-blocked-repairs-20260902 origin/staging
|
||||
```
|
||||
|
||||
读 `pre_work_error_ledger.md`，跑 `scripts/pre_work_check.py`，读 `frontend/AGENTS.md`，在 `docs/BUG_HISTORY.md` 检索（BUG-486 及相邻条目与本轮直接相关）。
|
||||
|
||||
**先读这几处再动手**：
|
||||
|
||||
- `frontend/src/lib/personal-report-generation.ts` —— `deriveVargaHousesFromEngine`（:336 附近）、`readAllVargaCharts` / `readVargaHouses`（`VARGA_KEY_ALIASES` 已存在）、`demoteThemesMissingRequiredCharts`、receipt upsert 逻辑
|
||||
- `frontend/src/lib/report-theme-evidence-plan.ts` —— 各主题 `requiredTechniqueGroups`（只读，不改）
|
||||
- `scripts/jyotish_api_server.py` —— `_attach_local_consultation_layers`、`execute_consultation_workflow`
|
||||
- `scripts/jaimini.py` —— 既有 Chara Karaka 实现
|
||||
- `git show 45f190a1` 与 `git show 643f6f7a` —— 昨日两次治标修复的全部内容
|
||||
|
||||
## 复现方法（验收也用它）
|
||||
|
||||
起本地引擎：`.venv/bin/python scripts/jyotish_api_server.py --port 5200`。用虚构出生数据（如 1993-06-15 10:30，lat 36.42 / lon 114.21 / tz 8）按 worker 的调用方式（`entryMode: "direct_chart"`，question `请为个人报告计算 <theme> 主题证据`）对 career/marriage/timing/wealth 各调一次 `runConsultationWorkflow`，把 4 个响应喂给 `buildReportEvidenceBundleV2`，检查 `claimCards` / `blockedSections` / `executionLedger` / `charts`。修复前的预期输出（用于确认复现成功）：claimCards 为空、四主题全在 blockedSections、charts 只有 D1。
|
||||
|
||||
---
|
||||
|
||||
## 任务 0（P0，门控）· Golden fixture 与形状契约
|
||||
|
||||
### 做法
|
||||
|
||||
- 用上述复现方法捕获 4 个主题的真实响应，裁剪成 fixture（保留 `chart.modules.varga_full`（至少 D2/D9/D10/D11/D24 各一张完整值）、`modules.transits`、`modules.jaimini`、`consumer_context`、machine packet sections；删除与提取无关的大块字段以控制体积），入库为测试资产。
|
||||
- 新增形状契约测试：断言 varga_full 值的真实形状（小写 `ascendant`、`sign_index`、`planets` 字典、`house_chart`），并断言 `modules.transits.status` 字段存在。**这个测试在修复前就应该通过**（它锁的是引擎真实形状，不是前端行为）。
|
||||
- 将 `643f6f7a` 手造的旧形状 fixture 替换为 golden 派生数据；按红线 9 在改动处注明原值与原因。
|
||||
|
||||
### 验收
|
||||
|
||||
- 形状契约测试直接对 golden fixture 通过；PROGRESS 记录 fixture 的捕获命令与裁剪规则。
|
||||
|
||||
---
|
||||
|
||||
## 任务 1（P0）· 修分盘值形状，复活结构化分盘图
|
||||
|
||||
### 做法
|
||||
|
||||
`deriveVargaHousesFromEngine` 兼容真实形状，规则：
|
||||
|
||||
- 上升：`varga.ascendant ?? varga.Ascendant`；星座索引 `sign_index ?? sign_idx ?? signIndex(sign)`；度数 `degree ?? degree_in_sign`。
|
||||
- 行星：优先读 `varga.planets` 字典（每行星有 `sign_index` 与 `house`，宫位可直接用 `house`，无 `house` 时按整星座宫从上升推导）；`planets` 不存在时退回旧的顶层行星键路径（保持对旧形状的兼容，两种形状都要有测试）。
|
||||
- 不吸收 `house_chart` 以外来源不明的字段；未知键一律不复制。
|
||||
|
||||
### 验收
|
||||
|
||||
- 单元测试双形状覆盖（golden 新形状 + 既有旧形状）。
|
||||
- 复现管线跑通后：`charts` 至少含 D1/D2/D9/D10/D11/D24；wealth 出 claim card，`demoteThemesMissingRequiredCharts` 不触发；D2/D11 回执 executed。
|
||||
- education / migration_home 等依赖分盘的主题在补充复现（9 主题全请求）中同样解锁，PROGRESS 记录逐主题结果。
|
||||
|
||||
---
|
||||
|
||||
## 任务 2（P0）· Transit 执行回执
|
||||
|
||||
### 做法
|
||||
|
||||
提取层读 `chart.modules.transits`：`status === "executed"` 时 upsert `Transit` 回执（`status: "partial"`、`executed: true`，与 ashtakavarga/dasha_sub_periods 的既有读取方式同风格）；`status` 缺失或非 executed 时不产回执（fail closed，不得默认 executed）。
|
||||
|
||||
### 验收
|
||||
|
||||
- 单元测试：executed / 缺失 / 其他 status 三种输入。
|
||||
- 复现管线：timing 出 claim card；career 的 blocked 理由只剩 AmK（在任务 3 完成前）。
|
||||
|
||||
---
|
||||
|
||||
## 任务 3（P0）· 引擎挂 Chara Karaka + 前端 AmK/DK 回执
|
||||
|
||||
### 做法
|
||||
|
||||
- 引擎：`_attach_local_consultation_layers` 调用 `scripts/jaimini.py` 既有实现，把 Chara Karaka 挂到 `chart.modules.jaimini.chara_karakas`（结构建议：`{ "AmK": { "planet": ..., ... }, "DK": { ... }, ... }`，具体键名以 jaimini.py 现有输出为准，**新增字段不改既有 `arudha_padas`**）。带 Python 单元测试。
|
||||
- 前端：从 `modules.jaimini.chara_karakas` 中 AmK/DK 的存在性 upsert `AmK` / `DK` 回执（`partial` + `executed: true`）；数据缺失时不产回执。
|
||||
- golden fixture 用引擎修复后的响应重新捕获（或叠加一份含 karakas 的 golden），形状契约测试同步覆盖新层。
|
||||
|
||||
### 验收
|
||||
|
||||
- Python 测试：consultation 响应含 `chara_karakas` 且 AmK/DK 数据来自 jaimini.py 现有输出。
|
||||
- 复现管线：**career/marriage/timing/wealth 四主题全部出 claim card，blockedSections 为空**；`executionLedger` 中 AmK/DK/Transit/D2/D11 均 executed。
|
||||
|
||||
### 止损
|
||||
|
||||
- 若 `jaimini.py` 现有实现无法在 consultation 输入上直接复用（缺参数、口径冲突），**停下**写 `BLOCKED.md`，不得重写算法、不得放宽最低证据组来绕过。
|
||||
|
||||
---
|
||||
|
||||
## 任务 4（P1）· 端到端与既有欠账
|
||||
|
||||
- 全套质量门：frontend `tsc --noEmit` / `eslint`（0 error）/ `tsx --test`（失败清单与基线逐条比对）/ `next build`；Python 相关测试真实跑过。
|
||||
- 部署后（委托方核对 health gitCommit）真实生成一份 personal_full 报告，验收：四主题有正文、不再全 blocked；顺带补上一轮欠的交付物——真实 writer 输出回溯抽查（≥3 处）与每章实测 `inputTokens`/墙钟对照（对照基线与 2 倍线裁决记录见 `PROGRESS-report-skill-parity-20260901.md` 与 `BLOCKED.md` 对应条目）。
|
||||
|
||||
## 不在本轮范围
|
||||
|
||||
- 主题最低证据组的增删改（决策记录 c）。
|
||||
- 引擎排盘算法、full-reading 路径、varga_full 既有形状的任何改动。
|
||||
- 知识包内容、writer prompt、成本优化（沿用已裁决结论）。
|
||||
- 章节并发、模型更换、计费、数据库结构。
|
||||
|
||||
## 收尾
|
||||
|
||||
- PROGRESS 文件名写 `PROGRESS-report-blocked-repairs-20260902.md`。
|
||||
- `docs/BUG_HISTORY.md` 新增条目（编号先对远端确认；根因 1 与 BUG-486 关联，注明 45f190a1/643f6f7a 是治标、本轮治本）。
|
||||
- 建议两次推送：任务 0+1+2（纯前端）一次；任务 3（引擎+前端）一次。staging push 触发全量构建+部署，全链路约 20 分钟，推送后核对 `https://staging.jyotisha.chat/api/health` 的 `.deployment.gitCommit`。
|
||||
- 不自行提升 main。
|
||||
|
||||
## 交付物清单
|
||||
|
||||
1. Golden fixture（真实响应派生）+ 形状契约测试；643f6f7a 旧 fixture 的替换说明
|
||||
2. `deriveVargaHousesFromEngine` 双形状兼容 + 测试；复现管线中 charts/D2/D11 复活证据
|
||||
3. Transit 回执提取 + 三态测试
|
||||
4. 引擎 `chara_karakas` 新增层 + Python 测试；前端 AmK/DK 回执 + 测试
|
||||
5. 复现管线修复前后对照：blockedSections 从 4 → 0，claimCards 从 0 → 4（9 主题全请求的逐主题表）
|
||||
6. 部署后真实报告验收 + 上一轮欠账（writer 输出回溯抽查、实测 tokens/墙钟对照）
|
||||
7. `docs/BUG_HISTORY.md` 条目、`BLOCKED.md`（任何触发止损的项）、`PROGRESS-report-blocked-repairs-20260902.md`
|
||||
8. 全套质量门实际输出（frontend 四件 + Python 测试）
|
||||
Reference in New Issue
Block a user