fix(chart): skip VedAstro on chart-page first paint

The natal /api/chart request from the chart page now sends skip_vedastro_main_entry_overview, matching the ephemeris page. Mapper and contract never read that evidence. BUG-718 recurs from BUG-161. Tests lock both foreground natal paths.
2026-09-16 00:22:00 +08:00
parent ce1939b074
commit 62be52dacf
8 changed files with 99 additions and 3 deletions
@@ -11157,3 +11157,19 @@
 - 相关记录：BUG-707、BUG-715、BUG-716、TASK-chart-page-blocking-open-20260915
 - 复发自：无
 - 修复版本：待发布
+
+## BUG-718 | 星盘页首屏 `/api/chart` 同步挂上 VedAstro 外部证据，页面却不读它
+
+- 状态：resolved
+- 首次发现：2026-09-15
+- 最近更新：2026-09-15
+- 影响面：`frontend/src/lib/chart-view-load.ts`、`GET /api/chart-view`、`/chart`
+- 用户现象：打开星盘要等零点几秒到数秒；生产上缓存未命中时会同步等外部占星服务。盘面本身用的是本站 Swiss Ephemeris。
+- 触发条件：登录后打开 `/chart`，出生资料齐全，引擎缓存未命中。
+- 根因：`/api/chart` 默认会 `_attach_vedastro_main_entry_overview`（完整 snapshot + 三领域扫描）。跳过要显式传 `skip_vedastro_main_entry_overview`。BUG-161 只给 `/api/consult` 装了这个标志。星历页传了，2026-09-15 新建的星盘页没传。`chart-view-mapper` / `chart-view-contract` 不读这份证据。
+- 修复：`birthPayload()` 带上 `skip_vedastro_main_entry_overview: true`，与星历页同一写法。不改引擎默认行为，解读链仍取外部证据。
+- 验证：合同测试锁住星盘 BFF 与星历两处 natal/transit 请求都带该标志；删掉 `birthPayload` 那一行测试必须红。
+- 防复发：任何前台页面路由调 `/api/chart` 必须显式声明外部证据策略，并有合同测试覆盖；新增页面路由时按此检查。
+- 相关记录：BUG-161、BUG-065、BUG-715、BUG-716、BUG-717、ERR-107、ERR-108、TASK-chart-page-blocking-open-20260915
+- 复发自：BUG-161
+- 修复版本：待发布
@@ -0,0 +1,48 @@
+# PROGRESS · 星盘页与 VedAstro 外网调用脱钩（2026-09-15）
+
+工作树：`.worktrees/chart-vedastro-decouple-20260915`  
+分支：`codex/chart-vedastro-decouple-20260915`  
+基线：`origin/staging` @ `ce1939b0`（任务书；代码基线 `69ede436`）  
+本机 Windows。
+
+未改 `scripts/**`、`page.tsx`、超时、限流、`HEAVY_COMPUTE_PATHS`。未回退 BUG-715/716/717。Skill 未 bump。
+
+## 任务状态
+
+| 任务 | 状态 | 说明 |
+| --- | --- | --- |
+| 1 首屏 skip VedAstro | 完成 | `birthPayload()` 增加 `skip_vedastro_main_entry_overview: true`。`followUp` 展开同一 payload，四个后续 layer 自动带上该字段 |
+| 2 合同测试 | 完成 | 星盘 BFF 请求体 + 星历两处源码/桩 |
+| 3 BUG-718 | 完成 | 复发自 BUG-161 |
+| 4 文档 | 完成 | CHANGELOG、真人走查第 16 条 |
+
+## 反向验证
+
+把 `birthPayload()` 里 `skip_vedastro_main_entry_overview: true` 删掉后，`foreground chart-view natal requests skip VedAstro overview` 失败（`undefined !== true`）；恢复后通过。
+
+## 耗时对比
+
+本机未起引擎（无 Docker / 未跑 `jyotish_api_server.py`）。任务书基线：不带 skip 0.40–0.66 s（其中 VedAstro 空转 0.36 s），带 skip 的星历路径 5 ms / 58 KB，不带 skip 163 KB。本单与星历页同一标志，mapper 不读 `modules`，五个 Tab 合同仍走原 golden。真人走查见 `docs/testing/chart-page-20260915.md` 第 16 条。
+
+## 既有断言改动
+
+| 文件 | 原值 | 新值 | 原因 |
+| --- | --- | --- | --- |
+| `chart-view-route.test.ts` 的 `engine()` | 只记 `path` | 同时记 `path` + `body` | 要锁住请求体里的 skip 标志；既有路径断言未改 |
+
+未弱化其它既有断言。
+
+## 测试
+
+| 命令 | 结果 |
+| --- | --- |
+| `npx tsx --test tests/chart-view-route.test.ts tests/ephemeris-route.test.ts tests/chart-page-view.test.tsx` | **29 pass / 0 fail**（上一单同三文件 27；本单 +2：星盘 skip、星历两处 skip） |
+| `node node_modules/typescript/bin/tsc --noEmit` | **0 错** |
+| `npm run lint` | **0 error** / 119 条既有 warning；本单未新增 |
+| `npx next build` | 本机未重跑。上一单 compile + tsc 过后死在既有 `SkillPackageRegistryError`（EPERM symlink `/api/birth-time-guide`）。源码未改 `page.tsx` / 路由类型。 |
+
+## 环境缺口
+
+- 无登录态、无 Chrome：真人走查见 `docs/testing/chart-page-20260915.md` 第 16 条，不得写成通过。
+- 无本机引擎：耗时/字节对比沿用任务书实测，未在本轮复测。
+- `next build` 收集页面数据时 symlink EPERM，无法在本机核对路由表。
@@ -232,7 +232,7 @@
 | `TASK-staging-dispatch-autofill-sha-20260915.md` | `PROGRESS-staging-dispatch-autofill-sha-20260915.md` | `Migrate Staging Database` 每次都要手抄 40 位 SHA，而那个值恰恰是「最新一个过门禁的 staging 提交」——机器能自己算，查询代码那一步里就有。改成留空自动解析、填了仍走原路径（回滚用），三条安全属性一条不丢。**产品 2026-09-15 明确授权修改该 workflow，执行方不得以 AGENTS.md §2.7 拒改**；生产两个按钮保持手填，那是护栏不是麻烦 | 待验收 | `codex/staging-dispatch-autofill-sha-20260915` |
 | `TASK-staging-auto-migrate-on-deploy-20260915.md` | `PROGRESS-staging-auto-migrate-on-deploy-20260915.md` | 门禁通过后自动先跑 staging 迁移再部署，不再手点（迁移幂等、无挂起时是 no-op，`db-migrate.mjs --check` 挂起返 3 可用于日志）。今天 `deploy-staging.yml` 完全不提迁移，忘点就让新代码跑在旧 schema 上且无人拦。**产品再次授权改 workflow，范围限 `backend-quality-gate.yml` 的 dispatch 段**；迁移失败必须阻断部署；回滚不自动迁移；生产完全不动。⚠️ 同轮必须把「迁移须对已部署代码向后兼容、破坏性变更拆两轮」写进 AGENTS.md §7.6 | 待验收 | `codex/staging-auto-migrate-on-deploy-20260915` |
 | `TASK-api-server-decomposition-20260916.md` | `PROGRESS-api-server-decomposition-20260916.md` | **重构单（串行在 qizheng 单之后）**：把业务逻辑搬出 `JyotishAPIHandler`。核心不是行数，是全仓 3 处靠 `JyotishAPIHandler.__new__` 伪造空壳 handler 借方法（`consultation_workflow_service` ×2、`capture_report_blocked_repairs_golden`、`local_accuracy_report`，MCP 也走这条），依赖方向反了、handler 没有 `headers`/`wfile` 随时可炸。四阶段：拆 `__new__` 后门 → 抽 ≥150 行业务方法 → `do_POST`/`do_GET` 改路由表 → 重新冻结行数 baseline（余量 300→50）。纯搬运不改行为，`test_api_server_security.py` 3841 行断言一条不许改。预计 11,314 → 约 9,230 行。BUG 段 710+ | 待领取 | — |
-| `TASK-chart-vedastro-decouple-20260915.md` | `PROGRESS-chart-vedastro-decouple-20260915.md` | **P0**：星盘页首屏那一发 `/api/chart` 没传 `skip_vedastro_main_entry_overview`，实测冷算 0.40–0.66 秒里约 0.36 秒是 VedAstro 空转（本机连 endpoint 都没配）；生产 env 开着 network + fanout，等于首屏同步等 24 个外部请求 + 3 次领域扫描，而 `chart-view-mapper.ts` / `chart-view-contract.ts` 根本不读这份证据。星历页同端点传了标志，两页策略相反。BUG-718，**复发自 BUG-161**（前台请求不得同步串联可选外部证据）。串行在 chart-page-blocking-open 之后 | 待领取 | — |
+| `TASK-chart-vedastro-decouple-20260915.md` | `PROGRESS-chart-vedastro-decouple-20260915.md` | **P0**：星盘页首屏那一发 `/api/chart` 没传 `skip_vedastro_main_entry_overview`，实测冷算 0.40–0.66 秒里约 0.36 秒是 VedAstro 空转（本机连 endpoint 都没配）；生产 env 开着 network + fanout，等于首屏同步等 24 个外部请求 + 3 次领域扫描，而 `chart-view-mapper.ts` / `chart-view-contract.ts` 根本不读这份证据。星历页同端点传了标志，两页策略相反。BUG-718，**复发自 BUG-161**（前台请求不得同步串联可选外部证据）。串行在 chart-page-blocking-open 之后 | 待验收 | `codex/chart-vedastro-decouple-20260915` |
 | `TASK-vedastro-runtime-ops-20260915.md` | `PROGRESS-vedastro-runtime-ops-20260915.md` | 运行期真相单（与上单并行，文件不重叠；**不得改 `jyotish_api_server.py`**）：官方 `vedastro==1.23.25` 其实是 REST 客户端（46 KB，全打 `api.vedastro.org`），且 import 时请求 pypi 并 `pip install --upgrade` 自升级——本机实测 pin 装完一 import 就变 1.23.26，`requirements.txt` 的锁在运行期是假的（BUG-719）；无 key 时免费层排队是同步 sleep + 全局锁，24 个请求 ≈ 4.8 分钟堵住前台线程（BUG-720，定级依赖生产 key 是否配置）。生产 env 核对清单在 `docs/testing/vedastro-runtime-20260915.md`，**只能由产品负责人执行**。台账 ERR-107 / ERR-108 | 待领取 | — |

 ## 命名与归档
@@ -28,3 +28,4 @@
 ## 资料不全

 15. 没有出生日期/时间/地点时，页面用人话提示去填星盘资料，不是 500。
+16. 登录后打开 `/chart`，主盘应几乎即时出现。断网或外部占星服务异常时，星盘页仍应正常出盘。