docs(reports): record BUG-601, progress notes and the manual walkthrough
Renumbered from BUG-599: staging took 599 and 600 from other sessions while this branch was in review. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr
This commit is contained in:
Jesse_Chen
co-authored by
Claude Fable 5
Claude Fable 5
parent
848e39e61f
commit
5565b6324e
@@ -9318,3 +9318,18 @@
|
||||
- 复发自：BUG-039（全球地点列漏授 service_role 的同类权限缺口）
|
||||
- 修复版本：迁移 `20260909010000`，待发布
|
||||
|
||||
## BUG-601 | 报告生成进度后端已产出，前端解析后一字未渲染，8 分钟只见转圈
|
||||
|
||||
- 状态：resolved
|
||||
- 首次发现：2026-09-09
|
||||
- 最近更新：2026-09-09
|
||||
- 影响面：`/reports/[reportId]` 生成等待屏、`personal-report-page.tsx`、`personal-report-route-core.ts`
|
||||
- 用户现象：生成个人报告后停在等待页，屏幕上只有一个 `InlineSpinner`、一句固定文案「正在生成报告，大约 10–30 秒」和「已等待 X 分 Y 秒」。实际耗时以分钟计，轮询预算 8 分钟。用户无从判断是在推进还是已经卡死，普遍在三分钟左右刷新或离开。
|
||||
- 触发条件：任何一次个人报告生成，必现。
|
||||
- 根因：两段断链。其一，`personal-report-page.tsx` 的 `classifyReportEnvelope` 已经把 `progressPercent` / `progressPhase` 解析进 `generating` 状态对象（原第 97–102 行），但该分支的渲染（原第 231–246 行）完全没有引用这两个字段，等待屏因此与后端进度无关。其二，`resolveReportRead` 只在 `row.status === "failed"` 时读取分章行，`reportView` 也不含分章字段，所以生成中根本没有任何章节状态离开服务端——即便前端想渲染也无数据可用。worker 侧的阶梯（`loading_context` 10 → `generating_report` 30 → `section:<id>` 30–85 → `persisting_report` 90）一直在正常写库，只是没有读者。
|
||||
- 修复：分章进度成为等待屏的主体。服务端在 `generating` 与 `failed` 两种状态下读取分章行（`ready` 路径不变，不增加查询）；新增 `personal-report-progress.ts` 把行状态映射为只读的四态 `done / failed / writing / waiting` 并随 `reportView` 下发，只带 `id` 与 `state`。等待屏按 phase 分三段：准备阶段保留 spinner，写作阶段换成"已完成 N / M 章"加按章分格的进度条与章节清单，收尾阶段回到 spinner。停滞满 90 秒（`REPORT_PROGRESS_STALL_MS`）时当前章文案改为「用时较长，仍在写」，该计时复用既有的一秒 tick，未新增定时器或 effect。
|
||||
- 验证：`frontend/tests/personal-report-progress.test.ts` 16 项全绿，覆盖：认领态判定为「正在写」而非按完成数顺推（字典序返回时顺推会指向 `timing` 而正确答案是 `marriage`）、phase 命名的章已完成、blocked 计入完成数且 `hasFailure` 为真、全 ready 与部分 blocked 两种收尾、90 秒停滞文案切换且不出现「第 N 次尝试」、准备/写作/收尾三分支、分章行缺失时回落准备态而非渲染「已完成 0 / 0 章」、面板无 percent/定时器/预计剩余、`attemptCount` 等后台字段不出服务端。全量 `npm test` 2929→2945（pass 2887→2903），失败 28 条与基线逐条一致（全部为无 Docker 的数据库/部署套件）。`tsc --noEmit` 0 错，`npm run lint` 0 error。
|
||||
- 防复发：三条写进 `frontend/DESIGN.md` §9「报告生成等待态」并由上述测试锁死。其一，进度条按章分格，不得改画百分比条——job 的 percent 在 0→30 与 90→100 是瞬间跳变，线性条会演出后端没做的动作。其二，"正在写哪一章"只能由行状态（`pending` 且已认领）判定，不得由 `section:<id>` 的 phase 名或"已完成数 + 1"推导：前者命名的是刚写完的那一章，后者在字典序列表上会指错。其三，界面上不得出现按定时器推进的插值动画或预计剩余时间。
|
||||
- 相关记录：BUG-043（禁止把后台评分状态渲染成用户需要管理的面板。本处边界不同且不冲突：等待屏是只读的，展示的是用户交付物自身的章节结构，`attemptCount`、原始错误码、lease、job id、payload 一律不出服务端）、BUG-576、BUG-574
|
||||
- 复发自：无
|
||||
- 修复版本：待发布
|
||||
|
||||
Reference in New Issue
Block a user