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 个与本轮无关的既有失败，详见交付说明，不能计入本轮回归失败。