feat(reports): generate card, jump to end, labelled export, TOC levels, table bands, export size; drop 字段 jargon (BUG-1092..1094)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01N4f2nya58RoRu4yEmJgRGE
2026-09-29 19:04:45 +08:00
parent 64aa0ec20c
commit d85ab9a2d2
21 changed files with 486 additions and 57 deletions
@@ -14688,6 +14688,50 @@
 - 复发自：无
 - 修复版本：未修

+## BUG-1092 | 报告技术页标题出现「字段」，行星主星表头是看不懂的 RL / NL / SL / SS / SB
+
+- 状态：resolved（代码 + 回归测试；未部署，真机待合入 staging 后复核）
+- 首次发现 / 最近更新：2026-09-29 / 2026-09-29
+- 影响面：`scripts/pl9_reader_export.py`（p3 / p6 / p17 三个 `####` 标题、p6 表头、`_strip_pl9_user_engineering_markers` 的 `field_状态` 替换）。
+- 用户现象：个人报告「出生资料与图盘」里出现「Birth Chart 星主与状态字段」「原版补充字段」；表头是 `Planet | RL | NL | SL | SS | 状态 | SB`，产品反馈「用户都不知道这是啥」。
+- 触发条件：任何 reader_main 报告；p3 / p17 补充表只在引擎返回对应原版资料时出现。
+- 根因：模板标题照搬了引擎侧的工程命名（field / 字段）和 PL9 原版缩写，没有做面向读者的命名。
+- 修复：标题改为「行星主星与状态」「出生资料补充」「特殊上升与派生点补充」；`field_状态` 改译「状态」；表头改为「行星 | 星座主 | 星宿主 | 分主 | 分分主 | 尊贵状态 | 力量比」，表下加一句名称说明（力量比 = `ishta_bala_pct / 100`，1 以上为达标）。
+- 验证：`tests/test_report_reader_main.py::test_reader_headings_drop_field_jargon_and_dignity_is_one_name`；虚构案例同机改前 / 改后两次渲染 diff 只含这几处文案（golden `frontend/tests/fixtures/report-reader-main-fictional.json` 按该 diff 打补丁，其余逐字节不变）。
+- 防复发：报告标题不得出现「字段」；新增表头用读者能懂的中文，缩写须在表下说明。
+- 相关记录：BUG-1093、TASK-report-reader-polish-20260929
+- 复发自：无
+- 修复版本：分支 `codex/report-reader-polish-20260929`
+
+## BUG-1093 | 报告尊贵状态显示成「入旺(入旺)」「中性(中性)」
+
+- 状态：resolved（代码 + 回归测试；未部署）
+- 首次发现 / 最近更新：2026-09-29 / 2026-09-29
+- 影响面：`scripts/pl9_reader_export.py` p6「行星主星与状态」与「宫主（Bhavesh）落宫解释」两张表的状态列。
+- 用户现象：状态列同一个词写两遍（入旺(入旺)、入庙(入庙)、中性(中性)），另有「入敌(敌对星座)」「极敌(Great Enemy)」中英混杂。
+- 触发条件：任何 reader_main 报告。
+- 根因：引擎 `DIGNITY_LABELS` 本身是中英双写（`入旺(Exalted)`）；reader 的汉化是全文逐词替换，把括号里的英文也译成中文，于是两边相同；glossary 里没有的词（Great Enemy）保持英文。
+- 修复：新增 `_dignity_label`，只取双写标签的中文部分；两张表的状态单元格都经它输出。引擎 `DIGNITY_LABELS` 不动（其它消费方依赖它）。
+- 验证：同 BUG-1092 的回归测试断言全文不再出现 `X(X)` 形式、两张表状态列无括号；`_dignity_label` 单测覆盖双写、纯中文、空值。
+- 防复发：reader 表格里的引擎枚举值先归一再进汉化，不依赖逐词替换处理括号。
+- 相关记录：BUG-1092
+- 复发自：无
+- 修复版本：分支 `codex/report-reader-polish-20260929`
+
+## BUG-1094 | 报告页可用性：生成入口不显眼、没有到底部、导出按钮找不到、目录层级分不清、表格行难对齐、导出不知道多大
+
+- 状态：resolved（代码 + 回归测试；未部署，浏览器级真机欠，见 `docs/testing/report-reader-polish-20260929.md`）
+- 首次发现 / 最近更新：2026-09-29 / 2026-09-29
+- 影响面：`personal-report-center.tsx`、`generate-personal-report-button.tsx`、`personal-report-markdown-view.tsx`、新增 `report-edge-jump.tsx`、`report-actions.tsx`、`report-export-drawer.tsx`、`lib/report-export-blocks.ts`、`globals.css`。
+- 用户现象（产品截图）：生成按钮是标题栏右上角的小描边按钮，空状态文案写「生成完整报告」而按钮叫「生成报告」；长报告没法一下到底；导出只是一个灰色图标；目录里「强度、关系与 Ashtakavarga 技术页」像上一组的子项；表格无底色；分块导出只显示字数。
+- 根因：入口与导出做成了次要样式；按章节懒渲染却没有配套的到底部；目录一级 / 二级只差 12px 缩进、同色同字重；报告表格沿用聊天的极简表格样式；导出计数只统计字符（图盘块含 SVG，与文件大小差距大）。
+- 修复：生成入口挪进页面顶部卡片（删标题栏按钮），下方「过往的报告」；右下角「到底部 / 回到顶部」单按钮，点击先 `flushSync` 挂载全部懒渲染章节再滚到 `scrollHeight`；导出改为带文字的描边按钮；目录一级加粗用 ink、组间留白，二级缩进 `--space-5`；仅报告表格加表头淡底与隔行底色（打印更浅）；导出弹窗显示 `TextEncoder` 实测字节（全篇与已选）。
+- 验证：`frontend/tests/report-reader-polish.test.tsx`（6 条）、`report-export-drawer.test.tsx` 新增文件大小用例；既有断言改动三栏见 `docs/tasks/PROGRESS-report-reader-polish-20260929.md`。
+- 防复发：报告页只有一个生成入口；到底部不得接入会话滚动锚；表格底色选择器限定在报告作用域。
+- 相关记录：BUG-1092、BUG-1093
+- 复发自：无
+- 修复版本：分支 `codex/report-reader-polish-20260929`
+
 ## BUG-1095 | 太阳返照本地时间是 UT 原样：读者版「Varshapravesha」差一个时区，Sahams 昼夜按错误时刻判

 - 状态：resolved（2026-09-29 Claude 独立验收通过：6 测试文件+隐私守卫 156 passed；基线树 vs 分支北京虚构盘 A/B：solar-return 6 处差异全为修正项、tajika 0 差异；快速门 Python 步 1001 passed / 1 skipped 与基线一致，npm 步为 worktree 无 node_modules 的环境缺口）
@@ -0,0 +1,35 @@
+# PROGRESS · 报告页打磨 · 2026-09-29
+
+> 任务书：`docs/tasks/TASK-report-reader-polish-20260929.md`。执行：Claude（直接执行模式，产品 2026-09-29「请你开始执行」）。
+> 分支 `codex/report-reader-polish-20260929`，基线 `origin/staging` = `6e393780`。BUG-1092～1094。
+
+## 交付对照
+
+| 编号 | 结论 | 说明 |
+|---|---|---|
+| R1 报告中心改版 | 完成 | 标题栏无按钮；`.report-center-create` 卡片居中放「生成报告」（实心，默认尺寸）；下方「过往的报告」；无报告时一行「还没有个人报告。」。按钮的防重复点击、`classifyCreateResponse` 未改 |
+| R2 到底部 | 完成 | 新组件 `report-edge-jump.tsx`；`LazyMarkdownSection` 新增 `forceVisible`，点击时 `flushSync` 挂载全部章节后滚到 `scrollHeight`；距底 480px 内变「回到顶部」，一次只显示一个 |
+| R3 导出按钮 | 完成 | 描边、默认高度、可见文字「导出」，`aria-label="导出报告"` 保留 |
+| R4 目录层级 | 完成 | 一级 ink / 600 / 组间 `--space-3`；二级缩进 `--space-5` |
+| R5 字段文案与表头 | 完成 | 三个标题、`field_状态`、p6 表头改中文 + 表下说明；状态列经 `_dignity_label` 去掉双写；同样的去重也用在「宫主（Bhavesh）落宫解释」表（排查时发现的同源问题） |
+| R6 表格底色 | 完成 | 只作用于 `.personal-report-table-wrap` 与 `.personal-report-fact-tables`；打印 5% / 2.5% |
+| R7 导出大小 | 完成 | `exportByteSize` = `TextEncoder` 字节；`formatExportSize` 显示「约 N KB / 约 N.N MB」；全篇与已选各一个 |
+
+## 既有断言改动（原值 / 新值 / 原因）
+
+| 文件 | 原值 | 新值 | 原因 |
+|---|---|---|---|
+| `frontend/tests/personal-report-view.test.ts`「ready reports expose only the back link and accessible export icon」 | `match size="icon"`、`match <Download aria-hidden="true" />`、`match title="导出"` | `doesNotMatch size="icon"`、`match variant="outline"`、`match <Download aria-hidden="true" />导出` | §3-3：图标按钮改为带文字的描边按钮。`aria-label="导出报告"`、返回链接、禁用项断言不变 |
+| `frontend/tests/report-export-drawer.test.tsx`「reader actions keep only the accessible export icon」 | `title` 等于「导出」 | 按钮文字等于「导出」，`title` 为空 | 同上。按钮数量仍为 1、对话框开合断言不变 |
+| `frontend/tests/personal-report-entry.test.ts`「entry stays on one line…」 | `match shrink-0` | `doesNotMatch shrink-0`（`whitespace-nowrap` 仍 match） | §3-1：按钮移出 46px 标题栏，不再与标题争宽；「一行不折」要求不变 |
+| `frontend/tests/react-client-lifecycle-test-support.ts`（测试宿主） | 无 `closest` / `scrollTo` | 增加按类名的 `closest` 与记录调用的 `scrollTo`、`scrollTop/scrollHeight/clientHeight` | 让「到底部」能在宿主里被真实点击验证；不影响其它用例（全量对比见下） |
+
+测试名均未改（名字里的 "icon" 保留，避免名单消失；语义以断言为准）。
+
+## Golden
+
+`frontend/tests/fixtures/report-reader-main-fictional.json`：用同一虚构输入（`tests/test_report_reader_main.py::FICTIONAL`）、同一引擎，分别以改前（`origin/staging` 的 `pl9_reader_export.py`）与改后模块渲染，取两者 diff 打到 golden 上。golden 与改前渲染本身只差一行 Shadbala 小数（`-18.80` / `-18.79`，同机两次运行也会抖动，与本单无关，未带入）。golden 改动 = 标题 1 行、表头 2 行、状态列 9 行、说明 2 行、宫主表状态 7 行。
+
+## 验证
+
+（见下方「命令与结果」，由 Claude 实跑填写）
@@ -0,0 +1,18 @@
+# 真机清单 · 报告页打磨（2026-09-29）
+
+对应 `docs/tasks/TASK-report-reader-polish-20260929.md`（BUG-1092～1094）。电脑（Chrome 或 Safari）和手机（iPhone Safari）各走一遍。用你自己的账号即可，不需要生成新报告（第 7 条除外）。
+
+| # | 操作 | 应该看到 | 结果 |
+|---|---|---|---|
+| 1 | 打开「我的报告」 | 标题栏右上角**没有**生成按钮；页面顶部一张卡片写「生成个人报告」，实心按钮「生成报告」在卡片正中；下方是「过往的报告」列表 | |
+| 2 | （没有报告的账号）打开「我的报告」 | 卡片下面只有一行小字「还没有个人报告。」，没有第二个大空框 | |
+| 3 | 打开一份已完成的报告 | 顶部操作栏右侧是带文字的「导出」按钮；右下角有「到底部」 | |
+| 4 | 刚打开报告就点「到底部」 | 一次就到文末最后的表格，没有停在半路；按钮变成「回到顶部」，点它回到开头 | |
+| 5 | 看右侧目录（电脑） | 「出生资料与图盘」「强度、关系与 Ashtakavarga 技术页」等章节名加粗、颜色更深，小节往里缩一级 | |
+| 6 | 滚到「出生资料与图盘」里的行星表格 | 表头有淡底，行与行之间隔一行一层很淡的底色；深色模式下同样能看出来 | |
+| 7 | 生成一份**新**报告后找「行星主星与状态」表 | 标题里没有「字段」；表头是「行星 / 星座主 / 星宿主 / 分主 / 分分主 / 尊贵状态 / 力量比」，表下有一句说明；状态列只写「入旺」「中性」这样一个词 | |
+| 8 | 点「导出」 | 弹窗第一行写着字数和「约 xxx KB」（全篇和已选各一个）；换「全部分盘」，已选大小明显变大 | |
+| 9 | 浏览器打印预览（Ctrl/⌘+P） | 看不到「到底部」按钮；表格隔行底色比屏幕上更浅但还看得出 | |
+| 10 | 打开任意聊天里有表格的回答 | 聊天里的表格和以前一样，没有加底色 | |
+
+旧报告（改动前生成的）第 7 条仍是旧标题，这是预期：报告内容在生成时就定下了，要看新标题请重新生成。