Jyotisha/TASK-report-longform-e2e-fail-20260907.md

# 任务书 · MD-only 首跑失败取证与修复（2026-09-07）

基线：`origin/staging` @ `7cf7705a`（开工 `git fetch` 后以 HEAD 为准）。

## 事故实证

- 2026-09-07 05:14 UTC 用户创建 personal_full（5 主题），**MD-only 路径第一次真实运行**：`failed / calculation_unavailable`，`progressPercent=30 / progressPhase=failed`（引擎调用阶段）。报告 id `de2c2efb-9f1e-4cc6-8dc3-72bdfdb3b977`，requestId `d17c27ef-2ceb-4dd8-af4d-12107b4de7e4`。当时部署 `72dd5e9d`（含 BUG-574 修复与 MD-only worker）。
- **委托方本地复现排除了代码路径**：最新 staging 代码起本地引擎，按 `buildLongformBirthPayload` 同形 payload（虚构盘 + provisional + candidate_range + packs:["full"] + markdown）POST `/api/professional_report_reference` → **HTTP 200、3.3 秒、315KB**。代码与合同没问题，失败是 **staging 环境特有**。
- detail API 未透出附录错误码（观测缺口，本轮补）。

## 两个可判别嫌疑（任务 0 一条查询定案）

`generatePersonalReportLongform` 失败时把错误类别写进 `personal_report_longform_appendices.last_error_code`：

| last_error_code | 含义 | 指向 |
|---|---|---|
| `upstream_unavailable` / `upstream_busy` | 引擎 HTTP 非 200 | **嫌疑 A：staging api 容器版本滞后**（web 随 deploy 更新，api 容器若未随部署重建，端点行为/参数支持与 web 不配套）或引擎在该输入上 500 |
| `generation_failed` | 非 LongformGenerateError（180s `AbortSignal.timeout` 的 TimeoutError 落这里） | **嫌疑 B：staging 上全量 pack 超 180 秒**（外部 VedAstro 网关串行拉满；本地 3.3s 是因外部层快速 blocked） |
| `empty_markdown` | 200 但空文 | 引擎版本/参数不配套的另一种表现（同嫌疑 A） |

## 任务 0（P0，门控）· staging 取证定案

1. 查 requestId `d17c27ef…` 的 appendix 行：`status / attempt_count / last_error_code`。
2. web 容器日志该时段 `[personal-report]` 行；api 容器访问日志有无对应 `POST /api/professional_report_reference` 及其耗时/状态码。
3. **api 容器运行版本**：镜像构建时间 / 容器内代码是否含 `professional_report_reference` 最新实现（gaps2 的 `e4d16b75` 级别）；对照 deploy 管线是否会重建 api 容器。
4. 从 web 容器内对 `api:5200` 手工 POST 同形 payload（虚构盘）计时与状态码。

PROGRESS 写明定案（A / B / 其他），再进任务 1。

## 任务 1（P0）· 按定案修复

- **定案 A（api 容器滞后）**：把 api 容器纳入部署链（或把"api 容器更新步骤"固化进 deploy 流程与 runbook），更新后复测；防复发：health 增加引擎版本/构建指纹字段，web 与 api 版本不配套时可见。
- **定案 B（超时）**：不许一上来就调大 180s——先量真实耗时构成（外部网关占比）；优先让报告路径的引擎调用带 `defer_optional_external_evidence`（或等价参数）跳过/并行可选外部证据（引擎已有该机制，consultation 前台路径在用），把确定性本地全量控制在可预算时间内；外部层缺席按诚实标签落 blocked 行（gaps2 静默跳过禁令继续适用）。超时值若仍需调整，用实测数据定，写 PROGRESS。
- 任何情况下：`calculation_unavailable` 保持 retryable 语义，但确认 job 三次尝试真实发生且每次都调用了引擎（时间戳对齐）。

## 任务 2（P1）· 观测补口

- detail API（失败报告）透出 appendix 的 `last_error_code`（错误码级，不含内容），报告页失败态显示可读原因——本轮取证难就难在这个码埋在表里。
- worker 引擎调用记录耗时与 HTTP 状态（数值日志）。

## 任务 3（P0 收尾）· 收官 smoke 重跑

修复部署后按 `docs/operations/personal-report-staging.md` smoke：列表/详情/创建，创建走到 ready——**这是报告线的最终收官项**：~30s（或实测预算内）ready、详情页 TOC/宽表、导出 .md、0 用量计费结算、新卡片 `card_summary` 显示。

## 硬红线

既有全部延续（迁移规范、诚实标签、静默跳过禁令、不改 `.gitea/workflows/**`、不提升 main、`./node_modules/.bin/tsc`、真实用户资料不入库、日志无内容）。**取证要快**——容器 recreate 丢日志的教训已发生过一次。

## 收尾

`docs/tasks/PROGRESS-report-longform-e2e-fail-20260907.md`；`docs/BUG_HISTORY.md` 条目（编号对远端）；不提升 main。

## 交付物清单

1. 任务 0 四项取证与定案
2. 按定案的修复 diff + 防复发项（api 版本可见性 或 外部证据 defer + 实测耗时表）
3. 观测补口 + 测试
4. 收官 smoke 全项记录