diff --git a/TASK-report-longform-parity-20260905.md b/TASK-report-longform-parity-20260905.md new file mode 100644 index 00000000..c9b864f8 --- /dev/null +++ b/TASK-report-longform-parity-20260905.md @@ -0,0 +1,97 @@ +# 任务书 · 长报告对齐全量版并挂入产品(2026-09-05) + +基线:`origin/staging` 最新(开工 `git fetch` 后以 HEAD 为准;出稿时约 `d2955c62` 之后)。 + +## 背景与对标结论 + +产品负责人提供了同一真实用户的两份长报告做对标(文件在其本地,**不得入库**):本地 Agent 调 skill 全量流程产出的"正式全量版"(391K/3634 行,`pl9_personal_long_report.v2`),与 Web 端一键导出的"多引擎参考版"(188K/2088 行)。委托方逐段对比结论:**两份出自同一引擎长报告生成器,差距全部在调用面、回放资产与装配参数,不需要新增引擎能力**——全量版就是"能力已存在"的活证据。 + +差距清单(按影响排序,验收对照表以此为准): + +1. **时间维度整块缺失**:参考版只有 1 个年度重点(且年度层大面积 blocked),缺三年展开(目标年+后两年)、缺"大运与时间主线"五系统状态表、缺三年逐月 KP 月度支持(`kp_monthly_report_packet`)、缺重点月份排序与行星换座节奏。 +2. **同模块状态更差**:Muntha `blocked`(全量版有值)、Mudda `blocked`(全量版三段可读)、Patyayini `missing_in_local`(全量版有段边界日期)——Web 路径没跑回放闭环或没开模块。 +3. **专题章深度 3–4×**:全量版事业章 48 行含 KP 结构小表(Ruling Planets/Promise 焦点)、KP 宫位 A/B/C/D 显著星核对表(2/6/10/11 宫)、逐月 MD/AD 月度支持表、年度 Sahams 坐标、敏感点层(Bhrigu Bindu / 22nd Drekkana / 64th Navamsa);参考版 13 行零表格。财运/关系章同构差距。 +4. **基础层缺口**:参考版本命主轴缺功能性吉凶行(含 Yogakaraka)、缺目标年龄换算;正文缺 Upagraha 表与 KP Lord/Sub 原始表。 +5. **阅读导航与质检层**:全量版开头约 115 行"成品阅读导航"(先读什么/结论等级规则/专题判读协议/质量验收矩阵/对照覆盖表),参考版没有。 +6. **校时敏感层**:全量版有生时敏感性矩阵(分钟级)+ 校时分钟排行;Web 路径没把候选窗传给生成器(候选窗现已可经 `read_report_candidate_range` RPC 取得)。 + +## 决策记录 + +产品负责人 2026-09-05 确认: + +- **(a)** Web 长报告生成路径对齐全量版调用面与装配(上述 1–6); +- **(b)** 长报告作为**全量数据附录/下载件**挂入 jyotisha.chat 报告页——五章叙事文档仍是主体验,两者并行、互不改写; +- **(c)** 授权为附录存储新增基础设施(新表或 Storage bucket + RLS 迁移,照既有迁移红线); +- **(d)** 附录生成为确定性计算,本轮**不新增计费**。 + +## 硬红线 + +1. **隐私**:那两份对标报告是真实用户资料,其正文、片段、出生数据一律不得进入仓库、fixture、测试或 PROGRESS;委托方给出的差距清单已脱敏,验收一律用虚构 smoke 盘。 +2. **五章叙事管线不动**:writer、bundle、schema、分章流程、既有防升级校验零改动。附录是并行产物。 +3. **附录生成不得阻塞主报告**:五章报告 ready 的时点与语义不变;附录异步生成/按需生成,其失败只使下载入口显示"暂不可用",不得影响主报告状态或触发退款。 +4. **真相边界延续**:生成器的 executed/blocked/parameter_sensitive 标签一个都不许为了"好看"改写;对齐是把没调的模块调起来、没装的层装进去,不是把 blocked 涂成可读。 +5. 存储迁移照既有红线(事务、幂等、RLS、显式 grant、`npm run test:db` 真跑,无 Docker 走 BLOCKED);下载鉴权=只能本人(或既有分享语义),必须有越权测试。 +6. 其余既有红线延续(不改 `.gitea/workflows/**`、不提升 main、`./node_modules/.bin/tsc`、遥测无内容)。 + +## 开工前置 + +```bash +git fetch origin --prune +git worktree add -b codex/report-longform-parity-20260905 \ + ../.worktrees/report-longform-parity-20260905 origin/staging +``` + +先读:`scripts/jyotish_engine.py` 长报告生成段(`## 多引擎口径说明` 模板约 :3146 起、`pl9_personal_long_report` 相关)、`scripts/report_pack_contract.py`、上游仓真源 `shared_full_report_authority.py` 的对应物、`frontend/supabase/migrations/20260904010000_read_report_candidate_range.sql`、`docs/tasks/PROGRESS-report-*.md` 历轮记录。 + +## 任务 + +### 任务 0(P0,门控)· 生成时长与覆盖基线 + +- 虚构 smoke 盘本地跑一次**全量模式**长报告:记录墙钟、产物行数/体积、各模块耗时大头(KP monthly 三年与 annual pack 是嫌疑)。 +- 产出"段落覆盖对照表":全量版目录的段标题清单(仅标题结构,无内容)对 Web 模式逐段标 `present / missing / degraded`,作为后续验收真源。 +- **止损**:若全量模式单次生成 > 5 分钟,任务 5 的产品接入必须选异步 job 形态并把时长数据摆进 PROGRESS,不得同步阻塞请求。 + +### 任务 1(P0)· 调用面与装配对齐(差距 1/3/4) + +多年 annual pack、三年 KP 月度、时间主线五系统状态表、专题章三表(KP 小表 / A-B-C-D 宫位核对 / 逐月 MD-AD)、年度 Sahams 与敏感点层、功能吉凶+Yogakaraka 入本命主轴与专题调用依据、目标年龄换算、Upagraha 表、KP Lord/Sub 原始表。验收:覆盖对照表中对应段全部 `present`,且状态标签如实。 + +### 任务 2(P0)· 年度层状态闭环(差距 2) + +查 Web 环境 Muntha / Mudda / Patyayini blocked 的具体根因(回放 artifact 未部署、开关未启、profile 不一致),能对齐则对齐;确因环境缺资产的,列 BLOCKED 并在报告内保持诚实标签(红线 4)。 + +### 任务 3(P1)· 校时敏感层(差距 6) + +生成入口接收候选窗(服务端经 `read_report_candidate_range` RPC 取得后传入),产出敏感性矩阵与分钟排行段;无候选窗时该段显示"未做校时"而非消失。 + +### 任务 4(P1)· 导航/质检层模板化(差距 5) + +"成品阅读导航"(先读什么、结论等级规则、专题判读协议、质量验收矩阵、覆盖表)由生成器确定性产出,不依赖 Agent 后处理;矩阵数值来自本次生成的真实状态。 + +### 任务 5(P1)· 挂入 jyotisha.chat + +- 主报告 ready 后异步生成附录(或首次请求时生成+缓存,按任务 0 数据定),存储走决策记录 (c);失败重试有限次后标"暂不可用"。 +- 报告页新增"全量数据附录"下载入口(MD;顺带评估复用现有打印导出通道)。 +- 鉴权与越权测试;`test:db` 真跑。 + +### 任务 6(P0 收尾)· 部署后真实验证 + +staging 部署后:真实生成主报告 → 下载附录 → 按任务 0 覆盖对照表逐段核对并给出 `present` 比例与剩余 `missing/degraded` 清单及原因。 + +## 不在本轮范围 + +- 五章叙事报告的内容/成本(成本线已终裁收口);上游 yinduzhanxing 仓的反向同步;PDF 排版美化;附录计费。 + +## 收尾 + +`docs/tasks/PROGRESS-report-longform-parity-20260905.md`;BUG_HISTORY 如涉及;建议分两批推送(任务 0–4 引擎侧一批、任务 5 产品侧一批);推送后核对 health `.deployment.gitCommit`;不提升 main。 + +## 交付物清单 + +1. 任务 0:时长/体积数据 + 段落覆盖对照表基线 +2. 调用面对齐 diff + 覆盖表逐段 `present` 证明(虚构盘) +3. 年度层状态闭环结论(修复项 + BLOCKED 项) +4. 敏感层接通 + 无候选窗降级表现 +5. 导航/质检层模板化输出样例(虚构盘) +6. 产品接入:迁移 + 越权测试 + 下载入口 + 失败降级 +7. 部署后真实核对:覆盖比例 + 剩余缺口清单 +8. 全套质量门实际输出 + PROGRESS