baodan/docs/PPT与海报Phase4至6补充实施记录_20260802.md

PPT 与海报 Phase 4～6 补充实施记录

日期：2026-08-02
对应计划：PPT与海报生成全链路详细修复计划书_20260802.md
结论：代码层已具备版本治理、冻结重放、输出失败关闭、留存清理和灰度观测能力；生产验收尚不能用“代码已完成”替代。

1. 本轮已实现

Phase 4：场景、策略与模板可执行化

• 新增 migrate_038 及场景、生成策略、PPT 模板三类不可变版本模型；生命周期统一为 draft -> validated -> published -> retired。
• 发布门禁要求使用已批准 Golden snapshot 试跑；发布后定义不可原地修改，只能复制为新草稿。
• 场景 resolver 使用文件数、险种、保司、产品、优先级和特异度确定唯一结果；无匹配和同优先级多匹配均失败关闭并返回 matchTrace。
• 运行时严格按 Scenario pageSpecs、Template pageSlots 和 GenerationPolicy 合并；缺页、重复槽位、容量溢出、资产 SHA 变化和不兼容版本均阻断。
• 管理后台已支持版本创建、JSON 编辑、校验、发布、试跑、复制、停用及失败原因查看。

Phase 5：冻结、对账与任务可靠性

• migrate_039 为统一任务补齐 snapshot/scenario/policy/template/asset/renderer、提交版本、对账、视觉检查和结果状态字段。
• PPT 与海报任务按实际使用的快照和配置完整冻结；重放只复用原任务冻结输入，不重新读取当前后台配置。
• PPTX 输出按 XML 可见文本和字段清单核对金额、币种和缺失字段；失败不产生可下载成功成品。
• 海报在生成背景前核对 renderDocument；最终浏览器合成时再次提交 DOM 导出清单，服务端校验：
  • PNG 实际尺寸；
  • DOM 与 PNG 尺寸一致性；
  • 必需模块存在且非空；
  • 文本裁切/溢出；
  • 可见文本 SHA-256；
  • 冻结文档与计划投影中的金额、币种。
• 最终校验失败时前端不再绕过服务端直接下载。
• 任务支持稳定幂等键、心跳、暂时性错误重试、冻结输入重放和 current/stale 结果标记。
• 旧 PPT 线程解析器已标记 deprecated；海报紧凑解析仅在关闭 DOCUMENT_IR_V1 时作为短期回滚路径，默认不再承担新链路事实职责。

Phase 6：质量、留存与灰度基础

• migrate_040 增加 Golden 审批字段和脱敏清理审计表。
• 管理后台可审批/撤销 Golden snapshot，并汇总文档、页面、OCR、表格、跨页表、冲突、快照、覆盖、版本、任务、重试、心跳、延迟、对账及视觉检查指标。
• 新增结构化质量告警：输出对账失败、视觉检查失败、运行任务无心跳、文档阻断和 Golden 数量不足。
• 留存策略覆盖 Document、Snapshot、GenerationTask、Poster、PPT History 和审计日志；支持 dry-run、批次上限、脱敏审计、存储根目录保护和失败记录。
• 新增只读孤儿文件检查，结果仅返回相对路径和 hash，不执行自动删除。
• 灰度开关支持按 profile 白名单和稳定百分比分桶：
  • DOCUMENT_IR_V1
  • PLAN_SNAPSHOT_V1
  • SCENARIO_ENGINE_V2
  • OUTPUT_RECONCILIATION_V1
  • RETENTION_CLEANUP_V1

2. 数据库迁移顺序

部署时须按现有迁移注册顺序执行，新增部分为：

1. migrate_038：场景、策略、模板版本；
2. migrate_039：任务冻结与输出审计；
3. migrate_040：Golden 与留存审计。

真实清理默认关闭。必须先执行 dry-run，核对候选及孤儿文件，再设置 INSURANCE_RETENTION_CLEANUP_V1=true 执行实删。

3. 建议上线顺序

1. 收集并脱敏不少于 30 份真实 PDF，完成双人标注，在“生成治理”页面批准为 Golden。
2. 由业务 SME 固化各险种允许的派生公式、缺失值和结论策略，创建并校验 GenerationPolicyVersion。
3. 上传带语义 shape name 的真实 PPTX 模板，逐页声明 pageType、slot 和容量，使用 Golden 试跑后发布。
4. 保持 SCENARIO_ENGINE_V2 默认关闭，按保司/profile 依次灰度 10% -> 30% -> 100%。
5. 每个阶段观察对账失败、视觉失败、无心跳和人工修改率；出现 P0 告警立即回退对应开关。
6. 连续观察期通过后关闭旧写路径；旧数据只允许只读查看和冻结输入重放。

4. 尚需外部输入或生产环境完成的验收

以下事项不能由仓库代码自动代替，因此当前不标记正式里程碑完成：

• 30 份获批脱敏 Golden 的双人标注及强制精确率门槛；
• 业务 SME 对公式、可比较性、缺失值和结论规则的签字；
• 真实生产模板的语义槽位标注、字体安装、图片差异基线和人工视觉验收；
• 生产队列、对象存储、数据库和告警通道上的 dry-run/实删演练；
• 10%/30%/100% 灰度及全量切换后的连续观察期。

因此，当前准确表述是：工程能力已覆盖 Phase 0～6 的主要代码任务并具备 M5 能力及 M6 基础，但 M2、M4、M6 的正式验收仍受真实样本、业务签字、模板资产和生产观察约束。

5. 本轮验证基线

• 后端计划相关专项回归：107 passed，1 skipped；
• 前端 TypeScript 检查：通过；
• 前端生产构建：通过；
• 治理页与海报页静态 UI 审查：无阻断项；
• 仓库全量 tests/ 中另有 2 个与本轮无关的既有失败，详见交付说明，不能计入本轮回归失败。