baodan/docs/PPT与海报首迭代Schema评审记录_20260802.md

# PPT 与海报首迭代 Schema 评审记录

## 评审范围

- `docs/schemas/document-ir.schema.json`
- `docs/schemas/field-value.schema.json`
- `docs/schemas/plan-data-snapshot.schema.json`

## 已冻结约束

1. 未知值使用 `null + missing`，真实数值 `0` 保留为数值；非法数字不能进入 FieldValue。
2. `conflict` 必须保留候选，不得静默覆盖；`derived` 必须记录公式且默认不参与排名、对账和结论。
3. 关键金额通过 EvidenceRef 指向文档页和 bbox；人工覆盖使用 `confirmed + overrideReason`。
4. Document IR 只保存版面事实，不决定保险业务字段最终值。
5. confirmed snapshot 的阻断数和冲突数必须为 0，并绑定 document SHA-256 与规范化 snapshot hash。
6. benefit row 的业务主键必须包含场景，后续迁移不得只按保单年度去重。

## 尚待业务确认

- 各险种的完整必填字段与合理范围；
- 可用于强校验的公式清单；
- 非保证场景、演示利率和提取前后口径；
- 跨产品可比条件；
- 文档、快照、证据和成品留存天数。

`migrate_036` 只保存文档版面事实，不固化上述保险业务口径，已在 Phase 1 落地；其中 `expires_at` 保持可空，留存决策完成前不启用自动清理。

`migrate_037` 已按冻结 Schema 落地不可变快照、字段证据与人工覆盖三类结构。该迁移只固化通用状态机、证据和版本约束，不内置尚未签字的保险公式；各险种完整必填范围、强校验公式、跨产品可比规则和留存期限继续保持配置未发布状态。未提供真实金标准前，新解析仍不得切为默认生产路径。
-												主要成果：
海报确认、文案生成、海报生成增加服务端失败关闭门禁，绑定文件哈希、解析快照哈希和确认数据哈希，并返回 422 业务错误。[validators.py (line 65)](D:/work/code/python/coding/baodanagent/api/insurance/plan_data/validators.py:65)
缺失金额不再转换为 0；删除错误字段兜底和“年缴×年期=合同总保费”事实推导；里程碑冲突会阻断确认。[normalizer.py (line 14)](D:/work/code/python/coding/baodanagent/api/insurance/ppt/normalizer.py:14)
PPT 渲染器支持可空金额和实际币种，缺失值显示“待确认”，避免 float(None)、空值除法等异常。
模板必须覆盖全部输入保司和产品；自动选择排序确定化，同优先级歧义时阻断。[template_selection.py (line 4)](D:/work/code/python/coding/baodanagent/api/insurance/ppt/template_selection.py:4)
场景判定写入 scenarioOverrideTrace，记录请求、模板、服务端及 Worker 最终判定。[routes.py (line 555)](D:/work/code/python/coding/baodanagent/api/insurance/ppt/routes.py:555)
前端增加哈希提交、人工调整原因、模板歧义提示及真实能力说明。
冻结三份核心 Schema，并建立 Goldens manifest、说明和评估脚本。
验证结果：
后端目标回归：111 passed, 1 skipped
PPT 运行时回归：81 passed
前端生产构建和 vue-tsc：通过
Python compileall：通过
三份 Schema JSON：解析通过
git diff --check：通过，仅有换行符提示

											
										
										
											2026-08-02 12:58:41 +08:00
+								# PPT 与海报首迭代 Schema 评审记录
 								## 评审范围
 								- `docs/schemas/document-ir.schema.json`
 								- `docs/schemas/field-value.schema.json`
 								- `docs/schemas/plan-data-snapshot.schema.json`
 								## 已冻结约束
 . 未知值使用 `null + missing`，真实数值 `0` 保留为数值；非法数字不能进入 FieldValue。
 . `conflict` 必须保留候选，不得静默覆盖；`derived` 必须记录公式且默认不参与排名、对账和结论。
 . 关键金额通过 EvidenceRef 指向文档页和 bbox；人工覆盖使用 `confirmed + overrideReason`。
 . Document IR 只保存版面事实，不决定保险业务字段最终值。
 . confirmed snapshot 的阻断数和冲突数必须为 0，并绑定 document SHA-256 与规范化 snapshot hash。
 . benefit row 的业务主键必须包含场景，后续迁移不得只按保单年度去重。
 								## 尚待业务确认
 								- 各险种的完整必填字段与合理范围；
 								- 可用于强校验的公式清单；
 								- 非保证场景、演示利率和提取前后口径；
 								- 跨产品可比条件；
 								- 文档、快照、证据和成品留存天数。
-												前工程开发已经推进到 Phase 6 基础能力，但正式验收还没有完成。更准确地说：Phase 0～5 的主要代码链路已经落地，Phase 6 完成了治理框架，尚缺生产化和真实数据验收。
阶段	当前状态	说明
Phase 0～3	基本完成	Document IR、证据链、人工确认、不可变 PlanData Snapshot、海报/PPT 投影已实现
Phase 4	代码完成	场景、策略、模板版本，校验/发布门禁，确定性 resolver 和严格槽位合并已实现
Phase 5	代码完成	输入冻结、PPTX/海报对账、失败关闭、幂等、心跳、重试和冻结输入重放已实现
Phase 6	基础完成	质量看板、结构化告警、Golden 审批、留存清理、孤儿检查和灰度开关已实现
正式上线	未完成	缺真实样本、生产模板、业务规则签字和灰度观察

目前验证基线：
PPT/海报专项测试：107 passed, 1 skipped
Vue TypeScript 检查：通过
前端生产构建：通过
代码变更仍在工作区，尚未提交
仓库全量测试仍有既有失败/挂起项，暂时不能宣称全仓测试完全绿色
仍未完成的代码任务主要有：
影子解析差异流水线
目前有灰度开关，但还没有完整的“新旧解析同时运行、字段差异入库、按保司/profile 聚合”的影子比较任务。

自动视觉回归
目前实现的是 DOM 模块、溢出、尺寸、文本和数值检查；还缺基于真实模板和标准图片的像素差异、字体缺失、遮挡和裁切回归。

告警通道接入
后台已经能产生结构化质量告警，但尚未自动推送到邮件、企微或其他通知通道。

留存任务生产化
dry-run、实删服务和失败审计已经具备，但尚未接入周期性 Celery/定时任务，也没有自动重试失败清理批次。

旧链路最终下线
旧 PPT 解析器和海报紧凑解析仍保留为回滚路径。需要全量灰度稳定后才能删除或彻底关闭写入口。

全仓测试收口
需要处理现有无关失败和挂起测试，建立真正全绿的 CI 基线。

仍需外部输入和生产环境完成的事项：
至少 30 份脱敏 Golden PDF，并完成双人标注和精确率验收。
业务专家确认派生公式、缺失值、可比较性和结论策略。
上传并标注真实生产 PPTX 的语义 shape、页面类型和容量。
安装生产字体并建立视觉基准图片。
实际执行数据库迁移 038～040。
完成留存 dry-run、实删演练以及 10% → 30% → 100% 灰度。
观察期通过后开启 SCENARIO_ENGINE_V2，目前它仍默认关闭；真实清理开关也默认关闭。
完整状态记录在 [PPT与海报Phase4至6补充实施记录](D:/work/code/python/coding/baodanagent/docs/PPT与海报Phase4至6补充实施记录_20260802.md)。

											
										
										
											2026-08-02 16:34:06 +08:00
+								`migrate_036` 只保存文档版面事实，不固化上述保险业务口径，已在 Phase 1 落地；其中 `expires_at` 保持可空，留存决策完成前不启用自动清理。
 								`migrate_037` 已按冻结 Schema 落地不可变快照、字段证据与人工覆盖三类结构。该迁移只固化通用状态机、证据和版本约束，不内置尚未签字的保险公式；各险种完整必填范围、强校验公式、跨产品可比规则和留存期限继续保持配置未发布状态。未提供真实金标准前，新解析仍不得切为默认生产路径。