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

工作树：`.worktrees/report-longform-e2e-fail-20260907`
分支：`codex/report-longform-e2e-fail-20260907`
任务书：`TASK-report-longform-e2e-fail-20260907.md`
基线：任务书 `58081a2d`；开工后 `origin/staging` 已含 `ed0cd087`（BUG-575 校时 UI）。事故当时健康检查 SHA 为已部署的 `7cf7705a`。

## 任务 0 定案

**定案 C：附录 persist 在自托管 upsert 上失败（不是 A，也不是 B）。**

| 项 | 证据 |
|---|---|
| 附录行 | `request_id=d17c27ef-…` 0 行；全表 `personal_report_longform_appendices` 也是 0 行 |
| Job | `failed / calculation_unavailable`，`attempt_count=3/3`，`progressPercent=30`，`05:14:15Z`–`05:15:48Z` |
| API 访问日志 | 三次 `POST /api/professional_report_reference` 皆 **200**：`05:14:42`、`05:15:14`、`05:15:48`（与 job 三次尝试对齐） |
| 容器版本 | web/api 同批 recreate `05:02Z`；web `GITHUB_SHA=7cf7705a`；api 镜像含 `format=markdown` / `packs`；含 gaps2 `e4d16b75` 祖先 |
| 任务 0.4 | 从 web 容器对 `api:5200` 虚构盘 POST：`http_status=200 duration_ms=26148 bytes=263471 format=markdown markdown_len=250452` |
| web 日志 | docker `LogPath` 空，近乎只有 Next 启动行；`[personal-report]` 不可见 |

排除：

- **A api 容器滞后**：端点存在且返回 markdown；web/api 同批部署。
- **B 180s 超时**：单次 26–32s，三次合计约 93s，均低于 `AbortSignal.timeout(180s)`。

根因：`persistLongformAppendix` 调用 `.upsert(row)`，自托管 `LocalPostgresQueryBuilder.upsert` 读取 `options.onConflict` 时同步抛错，引擎 200 的 markdown 从未入表。

未读取或写入真实用户正文/出生资料。

## 任务状态

| 任务 | 状态 | 说明 |
|---|---|---|
| 0 取证定案 | 完成 | 定案 C |
| 1 按定案修复 | 完成 | PK upsert + 本地客户端缺省主键；未调大 180s |
| 2 观测补口 | 完成 | 详情透出 `appendixLastErrorCode`；引擎 `http_status`/`duration_ms`；health `apiGitCommit` |
| 3 收官 smoke | 未部署 | 代码修复待 push/deploy 后按 `docs/operations/personal-report-staging.md` 重跑 |

## 实测耗时

| 路径 | HTTP | duration_ms | 备注 |
|---|---|---|---|
| 事故三次引擎调用 | 200 | ~32s / 次 | 与 job 三次尝试对齐 |
| 任务 0.4 虚构盘 | 200 | 26148 | markdown 250452 字符 |

未启用 `defer_optional_external_evidence`：真实耗时已在预算内。

## 质量门

定向 frontend / Python 源合同与附录 db 测（见提交说明）。未改 `.gitea/workflows/**`，不提升 main。

## BUG

`docs/BUG_HISTORY.md` **BUG-576**（远端 staging 已占用 BUG-575 给校时 UI）。修复提交 `e87c58d6`。