Jyotisha/docs/tasks/TASK-report-full-data-edition-20261007.md

# TASK · 个人报告改为完整数据版，删除阅读版（2026-10-07）

- 基线：`origin/staging` 合入 `TASK-upstream-sync6-20261007` 之后的 SHA（开工时记下）。写作时为 `0ed45a4b`。
- 上游参照：`/workspace/yinduzhanxing` `origin/main` @ `23be1807`，`scripts/jyotish_engine.py` 中的 `pl9_ai_density` 分支。
- 分支 / worktree：`codex/report-full-data-edition-20261007` / `.worktrees/report-full-data-edition-20261007`
- 串行顺序：等 sync6 合入 staging 后开工。可以与 `TASK-consult-card-full-source-20261007` 并行，但**两单都会动报告资料包的构建**（`build_professional_report_reference_packet`）：本单先合，对话单在本单之上 rebase。
- BUG 编号：与 sync6、对话单共用一个序列，开工时核对 `docs/BUG_HISTORY.md` 最大号。

## 1. 事故实证

产品 10-07 上传了一份上游导出的用户报告（英文，约 350 万字符），认为它的密度和准确度都远超网站报告。用乔布斯公开盘在两边各导出一份对照（复现方法：上游 `jyotish_engine.py pl9-export --pdf-edition pl9_ai_density --pack full`；我方 `scripts/professional_report_reference.py::build_professional_report_reference`，`edition=reader_main`、`packs=["full"]`、`include_fact_tables=True`）：

| 项 | 网站阅读版 | 上游完整数据版 |
| --- | --- | --- |
| 中文正文 | 7.6 万字符（另有事实表 JSON 约 49 万字符，只在网页表格里出现） | 97 万字符 |
| 开篇重点（当前大运；事业、财富、婚恋宫主带功能吉凶） | 无 | 有 |
| 九星逐星解释 | 无 | 有 |
| 宫主逐宫解释、Dosha 逐项 | 一张简表 | 完整 |
| 大运 / 子运解释 | 2 行 | 2,323 行 |
| 正文出现「功能」 | 0 次 | 44 次 |
| 其他大运（Narayana、Sthira、Niryaana Shoola、Drig、Navamsha、Lagna Kendradi、Shoola、Chara） | 无 | 有 |
| 年运解释、Mudda / Patyayini 表、Tajika 格局与强度、Sahams、Tripataki、月返照、八年总览 | 只有数据表 | 有表也有解释 |
| 结构化附录（功能吉凶层、单星八分表、KP 宫头征象星、Sudarshana、D81 / D108 / D144） | 无 | 有 |
| 英文独有原始数据（Argala、定位星链、双重过运、三年星历、Shadbala 分项、Avastha 输入、Vimsopaka 明细等） | 无 | 有 |
| 本机生成耗时 | 约 8 秒（排盘 1.2 秒 + 资料包 6.6 秒） | 34 秒（中文） |

## 2. 根因

我方移植报告时只搬了阅读版：`scripts/pl9_reader_export.py` 模块说明写明「`pl9_ai_density` is not ported」。缺的部分是上游 `jyotish_engine.py` 里的这些函数：`_render_pl9_ai_density_raw_data_markdown_en` / `_zh`、`_sanitize_pl9_ai_density_markdown` / `_en`、`_pl9_ai_density_visibility_receipt`、`_attach_pl9_source_visible_tables`，以及 `scripts/customer_timing_supplement.py`（`build_customer_timing_supplement`）。正文主体 `render_pl9_parity_markdown` 我方已经有（在 `pl9_reader_export.py` 里）。

## 3. 决策记录（产品 2026-10-07）

1. **删除阅读版**（中文、英文两种）。网站「生成报告」改为直接生成完整数据版，即上游 `pl9_ai_density` 的同等内容，中文、英文两份。
2. 「多余入口宁可删除」：阅读版的生成路径、切换入口和只为阅读版存在的代码一并删除，不保留开关。
3. 删除功能允许测试总数下降。这是对 AGENTS §7.3 的明确授权，范围仅限因删除阅读版而失去对象的测试。每删一条，在进度记录里写「测试名 / 原断言 / 删除原因」三栏；**守着计算口径的测试必须迁到新版本，不得删除**，见红线 2。
4. 已生成的旧报告（阅读版）必须仍能打开，只读，不自动重算。用户想要新版就重新生成。
5. 产品上传的那份用户报告只作为对照参考，**不得进入仓库**。

## 4. 硬红线

1. 正文的数值一律来自我方引擎（含 sync6 的修正）。不得因为移植上游渲染器，就把上游的计算函数一起带进来。上游渲染器读的字段我方没有时，写进缺口清单，不补算、不编。
2. 我方已经落地的报告口径**在新版本里全部保持**。下列测试改为对新版本断言，不删除：
   - `tests/test_report_chart_blank_columns.py`（BUG-1199～1203、1209：去 Kranti、八分法分栏、上升星宿、分盘尊贵、图盘不重复）
   - `tests/test_bhava_bala_formal.py`（BUG-1210：本站 +2 / −1.5 分不显示）
   - `tests/test_shadbala_minimum_first.py`（BUG-1208：先写 BPHS 最低要求，分档标为「网站分档」）
   - `tests/test_narayana_legacy_label.py`（BUG-1215、1218：旧算法标注，Rath 版并列）
   - `tests/test_chara_karaka_8_bphs_order.py`（BUG-1204）
   - `tests/test_neecha_bhanga_conditions.py`（BUG-1205：落陷取消列出成立的条件，不叫 Raja Yoga）
   - `tests/test_year_lord_basis_label.py`、`tests/test_year_lord_blocked_no_fallback.py`（BUG-1212、1214、1216、1217、1223）

   上游原始数据附录里如果出现这些规则禁止的写法（例如把 Neecha Bhanga 写成 Raja Yoga，或显示本站 bhava 分），一律按我方口径改写。
3. 隐私与泄漏：沿用 `tests/test_report_reader_main.py` 的 `LEAK_PATTERNS`（`blocked`、`executed`、`PyJHora`、`pl9_*`、`Traceback` 等）检查新版本中英文全文；上游自带的清理器只作补充，不能替代。
4. 计算档：按上游 `e4a6ac01` 的说法，客户版保持调用方给定的天文输入，解太阳返照时不加偏移，**不得启用**上游工程对标档里拟合的「视位置 / −5 秒 / 交点修正」。
5. `scripts/jyotish_api_server.py` 不增长：新代码放进新模块（建议 `scripts/pl9_full_data_export.py`），由 `professional_report_reference.py` 调用。`scripts/jyotish_engine.py` 只许极小的接线改动。
6. 前端：`tsc --noEmit` 0、`npm run lint` 0 error、`next build` 后 `/` 仍 Static、首屏 gzip 变化在 ±2% 以内；改 UI 的提交同时更新 `frontend/DESIGN.md`。
7. 不改 workflow、不提升 main。需要动表就真跑 `npm run test:db`（或按记忆里的本机 PG17 替身法），并在进度记录写明。

## 5. 任务分解

| # | 内容 | 验收标准 |
| --- | --- | --- |
| T0 | 盘点：列出阅读版在后端（`professional_report_reference.py` 的 `READER_MAIN_EDITION` / `REPORT_VERSION_READER`、`pl9_reader_export.py`、`pl9_reader_english*.py`、`reader_appendix_language*`、`reader_dasha_applicability.py`）和前端（`frontend/src/lib/personal-report-longform-generate.ts` 的 `fetchLongformMarkdown`、`personal-report-raw-appendix.ts`、`personal-report-longform-snapshot.ts`、`report-public-projection`、`frontend/src/components/personal-report/*`、`app/api/reports/[reportId]/raw-appendix`）的所有触点；标出哪些删、哪些改、哪些留 | 进度记录里有触点表；产品确认之前不删 |
| T1 | 后端移植：上述上游函数与 `customer_timing_supplement` 移进新模块；`build_professional_report_reference` 新增完整数据版（建议 `edition: "full_data"`、`report_version: pl9_personal_long_report.v4`），中英文各一份 | 乔布斯、奥巴马、泰勒、虚构盘四张盘中英文都能生成；章节目录与上游 `23be1807` 同盘导出逐节对照，缺节写进缺口清单并说明原因 |
| T2 | 英文清理闸 | 上游英文版在本机对乔布斯盘报错：`pl9 markdown hygiene failed ... chinese_characters:14981`。我方英文版四张盘全部通过清理闸，正文不含中文；过不了的写 BUG，并走既有的「英文暂不可用」路径，不得输出夹中文的英文报告 |
| T3 | 我方口径保持 | 红线 2 的测试全部迁到新版本并通过 |
| T4 | 前端切换与删除 | 「生成报告」只生成完整数据版；阅读版的切换、生成路径和组件删除；旧报告（v3）能打开（用 staging 或本机库里的旧记录验证，写明来源）；英文切换沿用 BUG-1126 的要求（切换后正文真的换） |
| T5 | 大体量显示 | 中文约 100 万字符、英文约 350 万字符时：报告页可以滚动、跳章节、搜索，不卡死；按章节分页或懒加载；提供 Markdown 下载（PDF 不在本单范围）。记录本机 Chrome 或 jsdom 下的首屏耗时与内存 |
| T6 | 生成耗时与存储 | 在 2 vCPU 档位下估算生成耗时，确认在 `ENGINE_TIMEOUT_MS = 180_000` 以内；单份报告存储体量（中 + 英）写进进度记录；超出现有列或接口上限时停下报告，不擅自改表 |
| T7 | 对话单的接口 | 新版本的资料包（packet）对外提供一个只读的取值入口，供 `TASK-consult-card-full-source-20261007` 按领域读取；本单只定义并测试这个入口，不改对话 |
| T8 | 记录 | `docs/BUG_HISTORY.md`、`CHANGELOG.md`（用户可感知：报告变成完整数据版）、`frontend/DESIGN.md`、`docs/tasks/PROGRESS-report-full-data-edition-20261007.md`、状态板、`docs/testing/` 真机清单（生成、打开旧报告、切换中英、跳章节、下载） |

## 6. 让步顺序

T5 的搜索 → T5 的懒加载（先只做按章节分页）→ T1 的英文独有原始数据段（先保证中英文正文齐全）。T2、T3、T4 中「旧报告能打开」这一条不让步。

## 7. 开工前置命令

```bash
git fetch origin --prune
git worktree add -b codex/report-full-data-edition-20261007 .worktrees/report-full-data-edition-20261007 origin/staging
grep -o "^## BUG-[0-9]*" docs/BUG_HISTORY.md | sed 's/## BUG-//' | sort -n | tail -1
```

## 8. 验收口径

Python：快速门 `failures []`、Python 全量失败名单 ⊆ 基线。前端：tsc / lint / `npm test` 失败名单与基线逐条相同（删除的测试另列）、build Static、gzip ±2%。真机走查留给 `docs/testing/` 清单，不得写成「通过」。