From e428e9d056ee1c444c9c480196977dffe8b3ed77 Mon Sep 17 00:00:00 2001 From: Jesse_Chen Date: Sun, 6 Sep 2026 12:01:04 +0000 Subject: [PATCH] =?UTF-8?q?docs(report):=20add=20MD-page=20task=20brief=20?= =?UTF-8?q?=E2=80=94=20render=20longform=20as=20the=20report,=20retire=20w?= =?UTF-8?q?riter?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_016P5RoqzmUQEbeC2qjAkeGr --- TASK-report-md-page-20260906.md | 67 +++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 TASK-report-md-page-20260906.md diff --git a/TASK-report-md-page-20260906.md b/TASK-report-md-page-20260906.md new file mode 100644 index 00000000..8f21316d --- /dev/null +++ b/TASK-report-md-page-20260906.md @@ -0,0 +1,67 @@ +# 任务书 · 报告详情页改渲染长报告 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