# PROGRESS · 报告详情页改渲染长报告 MD（2026-09-06）

工作树：`.worktrees/report-md-page-20260906`
分支：`codex/report-md-page-20260906`
基线：`origin/staging` 曾为 `e428e9d0`；第一次快进推送后 tip `809bdf13`
任务书：`TASK-report-md-page-20260906.md`（硬依赖 gaps2，已在同一 worktree 完成）
未改 `.gitea/workflows/**`，不提升 main。

## 开工回执

- 目标：新报告 worker 只生成 pl9 长报告 MD；详情页渲染该 MD；writer 停用保留；零模型用量必须结算。
- 顺序：gaps2 装配缺口 → MD-only 生成/计费 → 详情页 TOC/懒渲染 → 导出与报告中心 → 质量门。
- 最大风险：`complete_personal_report_job` 仍要合法 v2 封面文档；计费不得把 `actualModelId` 写成 `unknown`。

## 我替领导拍的板

- 计费：沿用 `report.full` 预留，结算 `inputTokens=0 outputTokens=0 costMicrousd=0`，`actualModelId` 用目录默认模型 id。缺少合法模型 id 时在报告标 ready **之前** 重试。
- 封面文档：最小合法 v2（主题走 blocked disclosure），页面不渲染。卡片摘要来自 MD「摘要」，写入封面 `executiveSummary.summary`，列表 JSON 路径不变。
- 旧报告：无附录 MD 显示「旧版本报告，请重新生成」。professional-reference POST 只读缓存，缺失 410。
- 导出：内存中同一份 MD；文件名 `个人报告-YYYY-MM-DD`。打印为次按钮。

## 任务状态

| 任务 | 状态 | 说明 |
| --- | --- | --- |
| gaps2 | 完成 | `PROGRESS-report-longform-gaps2-20260906.md`；BUG-561 / BUG-562 |
| MD-only 生成 + 计费 | 完成 | `PERSONAL_REPORT_WRITER_ENABLED=false`；附录失败即报告失败 |
| 详情页 TOC/懒渲染 | 完成 | `react-markdown` + `remark-gfm` + `skipHtml`；首屏导航+摘要 |
| 导出 / 报告中心 | 完成 | 「导出报告（.md）」；一步式等待文案 |
| staging 门禁 | 进行中 | `809bdf13` 已快进到 `origin/staging`；run 2446 失败。BUG-563 修复在 `ebc8380f`，本轮再推。 |
| 端到端 staging | blocked | 需门禁绿且 `/api/health` 的 `deployment.gitCommit` 离开 `a444c493`；无登录态/Chrome |

## 计费适配

1. 先加载模型目录，没有默认模型则 `model_unavailable`（可重试）。
2. 生成成功后 `actualModelId=catalog.defaultModelId`、0 token。
3. worker-core 若看到空/`unknown` 模型 id，在 `completeReportReady` 之前抛错。

## 首屏渲染

`frontend/tests/personal-report-longform-md.test.ts` 锁样例 SSR < 1500ms（本机约 30ms）。完整 ~250KB 报告的浏览器首屏仍待部署后补测。

## 质量门（实际跑过）

```text
pytest gaps2/timing/parity: 22 passed
frontend tsc --noEmit: pass
tsx personal-report-* + professional-reference + polling: 144 passed
markdown-view eslint: 0 error（修 BUG-563 后）
```

## 推送

- `cfcd369d` feat(report): render longform Markdown as the report and close gaps2 holes
- `8b140479` docs: record BUG-561/562 fix SHA
- `809bdf13` docs(report): record MD-page push SHA and keep markdown view locks
- `809bdf13` 已 `git push origin HEAD:staging`（`e428e9d0..809bdf13`）
- Gitea [backend-quality-gate #1131 / run 2446](https://git.copse.top/root/Jyotisha/actions/runs/2446) `validate` 失败：`Calling setState synchronously within an effect`（BUG-563）
- 未提升 `main`