Jesse_ChenandClaude Fable 5
e428e9d056
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr
68 lines
5.6 KiB
Markdown
68 lines
5.6 KiB
Markdown
# 任务书 · 报告详情页改渲染长报告 MD，writer 管线退役（2026-09-06）
|
||
|
||
基线：`origin/staging` 最新（开工 `git fetch` 后以 HEAD 为准；出稿时 `0c2a65b3` 之后）。
|
||
|
||
## 决策记录（产品负责人 2026-09-06 确认）
|
||
|
||
- **(a)** 报告详情页直接渲染长报告 MD（`pl9_personal_long_report.v2`，即现"全量数据附录"），MD 即报告本体，不再单独渲染一个五章版本。
|
||
- **(b)** **五章 writer 叙事管线退役**：新报告不再调用 writer / 分章生成 / `report_document` 装配；相关代码保留但停用（不删除，不再进新报告路径）。
|
||
- **(b2)** **旧报告不做兼容**（产品确认：当前仅一个用户，无存量包袱）：旧文档视图不维护、不分流；无附录 MD 的历史报告详情页显示"旧版本报告，请重新生成"即可。
|
||
- **(c)** 右上角"导出 PDF"改为"导出报告（.md）"（下载同一份 MD）；打印通道保留为次级入口（菜单或次按钮），不删。
|
||
- **(d)** 计费保持原价不变（价值定价）；MD 生成为确定性计算、零模型成本，结算逻辑必须适配"零模型用量"而不得因 usage=0 出错、退款或漏结。
|
||
|
||
## 依赖与顺序（硬性）
|
||
|
||
**`TASK-report-longform-gaps2-20260906.md`（@ 0ba8d56a + 58e1d397 追加）必须先于或随本单一并完成。** 页面渲染的就是那份 MD——它的内容质量从"附录质量"升级为"产品门面质量"；带着 KP 静默缺失、审计表零行上门面是不可接受的。执行方可同一 worktree 串行（先 gaps2 后本单）或分两批推送，但 MD 详情页不得在 gaps2 验收前对用户可见。
|
||
|
||
## 硬红线
|
||
|
||
1. **真相边界**：渲染层不得隐藏、折叠默认跳过或改写 MD 中的 blocked / conflict / parameter_sensitive 行——诚实标签是产品特色，不是待美化项。折叠交互允许，但默认展开状态必须让边界信息可见（阅读导航与质量验收矩阵不许折叠）。
|
||
2. **计费不得双扣/漏结**：新报告的预留-结算闭环适配零模型用量（固定事件结算或零用量 settle，方案由执行方按 `consultation-billing` 既有语义定，PROGRESS 说明）；不得出现预留后永不结算的悬挂。
|
||
3. **渲染安全**：MD 客户端渲染必须转义内嵌 HTML（react-markdown 默认行为，不得开启 rehype-raw）；不引入远程资源加载。
|
||
4. writer 代码只停用不删除；`personal_report_sections` 等表结构不动；数据库改动仅限必要的小迁移（如报告→附录关联/状态字段），照既有迁移红线并 `test:db` 真跑。
|
||
5. 其余既有红线延续（不改 `.gitea/workflows/**`、不提升 main、`./node_modules/.bin/tsc`、隐私日志边界、真实用户资料不入库）。
|
||
|
||
## 设计基准（执行方按此实现，偏离需在 PROGRESS 说明理由）
|
||
|
||
### 生成流程
|
||
|
||
- 创建报告 → worker 直接走既有 `professional-reference` 的生成逻辑（引擎 pl9-export full pack + 候选窗 RPC + provenance 字段〔gaps2 任务 4c〕）→ MD 存 `personal_report_longform_appendices` → 报告置 ready。
|
||
- 不再有 plan/section/summary/assemble 阶段；`progress_phase` 简化（如 `generating → ready`）；等待页文案改为一步式（预期 10–30 秒，含引擎全量 pack 约 8s + 传输落库）。
|
||
- 失败语义：引擎失败 → 既有 `calculation_unavailable` 路径；附录生成失败即报告失败（它现在就是本体，不再是"暂不可用"的附件）。
|
||
|
||
### 详情页渲染
|
||
|
||
- `react-markdown` + `remark-gfm`（表格）；样式复用 reading room 壳（`7b1354a7`）。
|
||
- **粘性目录**：从标题树（##/###）生成侧栏/移动端抽屉，锚点跳转 + 当前位置高亮；文档 170+ 标题，这是可用性的生命线。
|
||
- 宽表（KP 月度 10 列等）一律包 `overflow-x: auto` 容器；移动端为一等公民验收。
|
||
- 性能：约 250KB / 2700 行，按二级标题分段懒渲染（视口内挂载），首屏只出导航+摘要段；给出首屏渲染耗时实测。
|
||
- 报告中心卡片摘要：从 MD"摘要"段确定性截取（不再依赖 executiveSummary）。
|
||
|
||
### 导出
|
||
|
||
- 右上角主按钮"导出报告（.md）"→ 下载附录路由现有产物（文件名含报告日期）；打印保留次级入口。
|
||
|
||
## 任务
|
||
|
||
1. **（P0）生成流程切换**：worker MD-only 路径 + 计费适配 + 等待页/progress 简化 + 失败语义；writer 路径 feature-off（代码保留）。
|
||
2. **（P0）详情页 MD 渲染**：MD 视图为唯一详情视图（无附录的历史报告显示"旧版本报告，请重新生成"占位）+ TOC + 宽表 + 懒渲染 + 安全转义。
|
||
3. **（P0）导出按钮改造**：MD 主导出 + 打印次入口；文件名规范。
|
||
4. **（P1）报告中心适配**：卡片摘要来源、状态文案（不再有"章节 3/7"类进度）。
|
||
5. **（P0 收尾）端到端验收**：staging 部署后真实创建一份新报告——约 30 秒内 ready、页面 TOC/表格/移动端正常、导出 MD 与页面内容一致、计费结算记录正确。
|
||
|
||
## 不在本轮范围
|
||
|
||
- gaps2 的内容缺口本身（前置单）；PDF 排版美化；writer 代码删除；旧报告兼容或迁移（产品已明确放弃）；MD 的 AI 问答/划词解读（未来方向另立项）。
|
||
|
||
## 收尾
|
||
|
||
`docs/tasks/PROGRESS-report-md-page-20260906.md`；BUG_HISTORY 如涉及；推送后核对 health；不提升 main。
|
||
|
||
## 交付物清单
|
||
|
||
1. MD-only 生成路径 + 计费适配说明与结算记录证据
|
||
2. 详情页渲染（TOC/宽表/懒渲染/安全）+ 首屏耗时实测 + 移动端截图
|
||
3. 导出与打印入口改造
|
||
4. 端到端真实报告验收记录
|
||
5. 全套质量门实际输出 + PROGRESS
|