baodan/docs/PPT与海报生成全链路详细修复计划书_20260802.md

PPT 与海报生成全链路详细修复计划书

编制日期：2026-08-02
依据文档：docs/PPT与海报生成全链路深度审计报告_20260802.md
适用范围：计划书 PDF 解析、人工复核、PlanData、海报生成、PPT 生成、场景与模板、异步任务、质量门禁、测试、监控与数据留存
文档性质：实施主计划。既有 PPT、海报和 PDF 专项计划继续作为局部设计参考；若与本计划冲突，以“统一事实快照、字段证据链、失败关闭、版本可追溯”四项原则为准。

2026-08-02 实施说明：计划中的代码基础、治理接口和失败关闭门禁已推进至 Phase 6；实际里程碑仍须以 30 份获批金标准、真实模板试跑、业务公式签字和灰度观察结果验收。详见 docs/PPT与海报Phase4至6补充实施记录_20260802.md。

1. 结论与实施决策

本次整改不能按“海报修一套、PPT 再修一套”的方式推进。审计报告中的 55 项问题共享四个根因：事实来源分裂、字段语义失真、配置运行时失效、任务与输出不可复现。因此，修复主线确定为：

1. 先止损：阻止空数据、未知值、错误币种、错误字段兜底和不兼容模板继续进入成品；
2. 再建事实层：PDF 先形成保留页码、坐标、表格和 OCR 信息的 Document IR；
3. 再建唯一快照：人工确认后生成不可变 PlanData Snapshot，海报与 PPT 只能消费该快照；
4. 再重构配置：场景负责业务规则，模板负责视觉槽位，生成策略负责兼容、缺失和阻断；
5. 最后封闭交付：任务冻结全部输入，输出数值与快照逐项对账，P0 不一致时失败关闭。

不得把“有字段”“能打开 PPTX”“测试通过”当作准确性验收。上线以真实脱敏 PDF 金标准集、字段证据完整率和输出数值一致率为准。

2. 目标、边界与工作假设

2.1 核心目标

• 同一份 PDF 只产生一套经过确认的事实数据；
• 每个进入海报或 PPT 的关键金额都能定位到 PDF 页码和区域，或有明确的人工录入理由；
• missing、conflict、derived 与真实数值 0 在全链路中严格区分；
• 后台发布的场景、模板和生成策略实际控制生成结果，并可回放；
• 异步任务提交后不再受会话、模板和配置后续修改影响；
• 成品中的文本、表格和图表数值与提交时快照 100% 对账；
• 客户 PDF、解析中间产物、确认快照和成品都有明确留存、鉴权和清理闭环。

2.2 本计划不做的事项

• 不优先扩充大模型提示词、模板风格或新海报版式；
• 不把大模型作为密集金额表逐格抄录的唯一方案；
• 不把现有不可信旧解析结果批量标记为 confirmed；
• 不在首期实现跨币种收益排名或实时汇率换算；
• 不改 BaoDan/Dify 基座中除现有路由注册约定之外的代码；
• 不顺带重构与 PPT、海报、文档解析无关的模块。

2.3 工作假设

• 当前仓库迁移已到 migrate_035，本计划从 migrate_036 起分批增加可回滚的增量迁移；
• 第一批正式金标准不少于 30 份脱敏计划书，至少覆盖 3 家保险公司、3 类险种及原生/扫描/混合 PDF；
• 业务字段由保险业务人员确认口径，技术团队不自行推断“退保价值等于身故保障”等规则；
• 旧接口需要在灰度期兼容，但所有新生成任务必须可识别所使用的数据契约版本；
• 文档审计中的发生比例仍需真实样本测量，因此工期使用区间，不承诺单点日期。

3. 当前代码基线与修复约束

以下事实已结合当前代码核验，作为实施起点：

领域	当前代码事实	修复约束
海报解析	poster/tasks.py 优先执行 extract_for_poster，只有映射结果失败才回退完整解析	过渡期先收紧完整性门，最终删除独立事实解析，只保留 PlanData projection
海报确认	poster/service.py::confirm_case_upload 直接保存 confirmedData，未校验解析状态、必填、冲突、证据和文件哈希	前端校验只能改善体验，最终门禁必须在后端
海报复核	PosterSourcePanel.vue 仅编辑基础字段和 10/20/30 年值，未挂载 PDF 预览和完整利益表	先复用已有 PdfPagePreview.vue，不另造第二套 PDF 查看器
数值语义	normalizer.py 多处把缺失/非法值转为 0，仍存在字段互相兜底和保费乘年期推导	先引入兼容型 nullable 语义，再切换到 FieldValue；不可一次修改全部渲染器后才测试
场景	前后端均存在硬编码检测，运行时重新推断场景	场景解析只保留服务端单一入口，返回 matchTrace
模板	scenarioSlides 优先于后台 slidesConfig；模板上传可直接置 clone_ready=True	先明确临时优先级，再建立 pageSpec-slot 契约和发布门禁
任务快照	已有 input_snapshot_json 和 input_revision，但 Worker 仍读取当前 session/template	扩展现有任务模型和创建流程，不另建平行任务系统
留存	清理逻辑覆盖部分海报成品和 PPT 历史，但未覆盖源 PDF、case、Document IR、快照和证据	新数据必须在同一版本同时接入鉴权与清理

4. 目标链路与责任边界

PDF 上传
  -> Document Ingest（哈希、鉴权、页数、文件类型）
  -> Document IR（页面、bbox、文本块、表格、OCR 候选）
  -> Extraction Candidates（正则、profile、表格解析、LLM 语义候选）
  -> Reconciliation（字段语义、业务规则、冲突与场景归属）
  -> Review（PDF / 字段 / 表格双向定位）
  -> Confirmed PlanData Snapshot（不可变、版本化、可追溯）
  -> Poster Projection / PPT DeckContract
  -> ScenarioDefinition + GenerationPolicy + TemplateDefinition
  -> Frozen Generation Input
  -> Render
  -> 数值对账 + 视觉检查
  -> 成品或失败报告

模块职责必须保持清晰：

模块	唯一职责	禁止行为
api/insurance/document/	保存 PDF 的版面事实和解析过程	直接决定保险字段最终值
api/insurance/plan_data/	候选合并、业务校验、人工确认、快照、投影	为了适配某个海报模板修改事实
api/insurance/ppt/	将 PlanData 转为 DeckContract 并渲染 PPT	重新解析 PDF 或静默补造金额
api/insurance/poster/	将 PlanData 投影为海报内容并渲染	维护独立计划书事实或覆盖里程碑值
api/insurance/generation/	解析场景、冻结输入、调度、对账、追溯	在 Worker 中读取可变业务状态
管理后台	编辑、验证、发布场景和模板版本	修改已发布版本的内容

5. 数据模型与迁移计划

5.1 migrate_036：Document IR 与文档访问

新增表：

• insurance_documents
  • id、user_id、sha256、storage_key、original_name、mime_type、file_size、page_count；
  • document_type、pdf_kind（native/scanned/mixed）、status；
  • parser_version、ocr_version、profile_code、profile_version；
  • quality_json、processing_log_json、expires_at、时间字段；
  • 唯一约束建议为 (user_id, sha256)，不得跨用户复用授权。
• insurance_document_pages
  • document_id、page_number、width、height；
  • native_text_quality、ocr_quality、page_class；
  • text_blocks_json、ocr_blocks_json、images_json；
  • 唯一约束 (document_id, page_number)。
• insurance_document_tables
  • document_id、table_id、scenario_type、headers_json、rows_json；
  • source_pages_json、continuation_of、bbox_json、conflicts_json。

取舍说明：文本块和表格首期以 JSON 按页/表存储，避免把每个 PDF 单元格展开成海量数据库记录；需要检索的字段证据单独结构化存储。

5.2 migrate_037：PlanData、证据与确认快照

新增表：

• insurance_plan_snapshots
  • id、document_id、schema_version、snapshot_version、previous_snapshot_id；
  • status（draft/review_required/confirmed/superseded/invalid）；
  • plan_data_json、validation_results_json；
  • snapshot_hash、document_sha256、confirmed_by、confirmed_at、created_at、expires_at；
  • 唯一约束 (document_id, snapshot_version) 和 snapshot_hash 索引。
• insurance_field_evidence
  • snapshot_id、field_path、document_id、page_number、bbox_json；
  • table_id、row_id、column_id、raw_text、text_hash；
  • extractor、extractor_version、confidence、evidence_status。
• insurance_plan_overrides
  • snapshot_id、field_path、old_value_json、new_value_json；
  • reason、operator_id、created_at。

核心约束：

• confirmed 快照内容不可原地更新；修改必须派生新版本；
• snapshot_hash 对规范化 JSON 计算，字段排序、数字精度和空值表达必须固定；
• confirmed 前关键字段的 conflict 数量必须为 0；
• 每个导出关键金额必须存在证据，或存在人工覆盖记录和原因。

5.3 migrate_038：场景、策略与模板版本

保留现有 insurance_ppt_scenarios 和 insurance_ppt_templates 作为稳定标识与当前指针，新增版本表：

• insurance_ppt_scenario_versions
  • scenario_code、version、lifecycle（draft/validated/published/retired）；
  • selector_json、page_specs_json、metric_specs_json、comparison_years_json；
  • compatibility_rules_json、fallback_scenario、definition_hash；
  • published_by、published_at。
• insurance_generation_policy_versions
  • code、version、lifecycle；
  • calculation_policy_json、missing_value_policy_json、conclusion_policy_json、policy_hash。
• insurance_ppt_template_versions
  • template_id、version、lifecycle；
  • asset_id、asset_sha256、page_slots_json、theme_json、capacity_rules_json；
  • supported_scenario_versions_json、validation_report_json、definition_hash。

已发布版本禁止更新，只能创建新版本。旧的 slides_config_json 在兼容期只读映射为 draft version，不自动视为 validated/published。

5.4 migrate_039：任务冻结与输出审计

扩展 insurance_generation_tasks：

• snapshot_id、snapshot_hash、scenario_version_id、scenario_hash；
• policy_version_id、policy_hash、template_version_id、template_hash、asset_sha256；
• renderer_version、submit_revision、output_reconciliation_json、visual_check_json；
• heartbeat_at、attempt_no、result_state（current/stale/failed） 。

扩展 PPT/海报历史记录，保存实际使用的快照、场景、策略、模板和渲染器版本。不得只保存请求中的 template_id。

5.5 migrate_040：留存策略与清理审计

• 为 Document、Page、Table、Snapshot、Evidence、Override、PPT/海报成品增加 expires_at 或可推导的留存策略；
• 新增不含敏感正文的清理审计记录；
• 清理逻辑按依赖顺序删除对象文件和数据库数据；
• 清理任务支持 dry-run、批量上限、失败重试和孤儿文件检查。

所有迁移必须满足：可重复执行、启动失败即停止、先加后切、旧字段灰度期可读、不在迁移中执行耗时 PDF 重解析。

6. 分阶段实施计划

Phase 0：止损、基线与开关（P0，4～6 人日）

目标

在统一事实层完成前，先阻止已知错误继续进入海报和 PPT，并建立可以量化修复效果的基线。

任务包

P0-A：海报确认与生成后端门禁

关联问题：P0-05、P0-06、P0-07、P1-08、P1-16、P2-01。

修改：

• 为 confirm_case_upload 增加服务端 schema；
• 只允许 parse_status in ('parsed', 'partial') 进入确认，partial 必须补齐必填并解决冲突；
• 验证 file_hash、解析快照哈希和当前 case 一致；
• 按险种校验年龄、性别、币种、保费、缴费期、保额和关键利益字段；
• 检查所选产品与 PDF 提取产品；不一致时必须提交 overrideReason 并写审计记录；
• 空对象、非法数字、未解决冲突、无证据关键金额一律返回 4xx 业务错误；
• 生成接口再次执行同一门禁，不能信任 confirmed_data is not None；
• parsed 只表示“可复核”，只有 confirmed 快照可用于生成。

主要文件：

• api/insurance/poster/service.py
• api/insurance/poster/routes.py
• api/insurance/poster/tasks.py
• api/insurance/models/poster_case_upload.py
• 新增 api/insurance/plan_data/validators.py 的兼容入口

验收：

• {}、错误状态、缺必填、未解决冲突均无法确认；
• 绕过前端直接请求同样被阻断；
• 已确认数据修改后必须重新确认；
• 错产品不会被后台选择静默覆盖。

P0-B：修正未知值、错误兜底和币种

关联问题：P0-11、P0-12、P0-13、P1-12、P1-13、P1-14、P1-15。

修改：

• 新增 nullable 数值转换函数，明确区分 None、非法、0；
• 停止以 deathBenefit 写入 totalSurrenderValue；
• 停止 sumAssured -> deathBenefit、现金价值字段互相兜底；
• 停止把 annualPremium * payYears 当合同总保费；需要展示时标记 derived_estimate，默认不参与对账、排名和结论；
• 海报字段取值从 Python or 改为显式 is not None；
• 显式里程碑与利益表同年值不一致时产生冲突，不覆盖；
• 渲染器统一使用 currency 和 currency_symbol，删除所有硬编码 US$；
• 兼容期渲染器对未知值显示 — 或“待确认”，不得显示 0。

主要文件：

• api/insurance/ppt/normalizer.py
• api/insurance/ppt/comparison.py
• api/insurance/ppt/validator.py
• api/insurance/ppt/scripts/fast_pptx_renderer.py
• api/insurance/poster/tasks.py
• api/insurance/poster/content_builder.py

验收：

• 真实 0 保留为 0；缺失和非法值均不变成 0；
• 退保价值与身故保障不再互相替代；
• HKD、CNY、SGD、USD 样本的所有页面币种一致；
• 缺失金额不会进入排名、IRR 或“更优”结论。

P0-C：模板适用性、排序与后台诚实提示

关联问题：P0-08、P0-09、P1-18、P1-20、P2-03。

修改：

• 前后端多产品模板适用条件统一为“所有输入产品均满足”；
• 自动模板查询增加稳定排序：精确场景、产品覆盖、优先级、版本、ID；同优先级多个匹配时阻断；
• 在场景系统完成前，后台明确标注现有 slidesConfig 仅影响视觉页框/元数据，不能承诺控制业务页面；
• 记录临时 scenario_override_trace，把硬编码检测、用户选择、模板标签和最终场景全部写入任务日志；
• 生成页文案与真实能力一致，暂不展示不存在的“手动选择场景”。

验收：

• 任一产品不适用时模板不可选且后端拒绝；
• 同一输入重复自动选模板结果稳定；
• 管理员能看到当前配置是否只作为视觉配置使用。

P0-D：金标准与回归基线

关联问题：P0-17、P2-08。

修改：

• 建立脱敏样本登记表、标注规范和双人复核流程；
• 首批 10 份用于开发探针，Phase 2 前扩充到不少于 30 份；
• 标注标量、完整利益表、场景、页码、bbox、币种、单位和允许的空值；
• 将当前解析结果、耗时、人工修改率和 PPT/海报输出保存为基线，不把当前值当正确值；
• 新增批量评测命令，输出 JSON 和 Markdown 差异报告。

建议文件：

• tests/fixtures/plan_goldens/manifest.json
• tests/fixtures/plan_goldens/labels/*.json
• tests/plan_data_golden_test.py
• scripts/tools/evaluate_plan_goldens.py

Phase 0 出口门禁：所有止损测试通过；10 份样本可批量运行；确认和生成接口无法绕过门禁；不开启新架构开关时现有已确认记录仍可查看。

Phase 1：Document IR 与字段证据基础（P0，7～10 人日）

目标

解决“字符可读但页、表、行、列归属错误”的根因，保留后续对账所需的几何和来源信息。

任务包

P1-A：统一文档摄取

关联问题：P0-02、P1-01、P1-02、P1-03、P1-11。

• 新建 api/insurance/document/ingest.py，统一计算 SHA-256、文件类型、页数、存储键和权限；
• 新建 pdf_classifier.py 判断 native/scanned/mixed，不再只依赖全文乱码率；
• 按页保存文本块、读取顺序、bbox 和质量，不再使用 120000 字符全局硬截断；
• OCR 由“最多 40 页”改为按页质量和任务预算调度，超过预算时明确 partial/blocked；
• 缓存键包含文档哈希、parser/OCR/profile/规则/model/prompt 版本；
• 文档读取失败、加密、超限和低质量返回结构化错误。

P1-B：表格恢复与跨页关系

关联问题：P0-03、P0-04、P1-04、P1-05。

• 新建 layout.py、tables.py；保留线条、坐标聚类、表头层级、合并单元格和单位；
• 续页识别使用表格边界、列坐标、表头指纹和页间连续性，不只依赖关键词；
• 行主键改为 (table_id, scenario_type, policy_year, row_variant)，禁止只按 policy_year 去重；
• source_page 由解析器根据真实块坐标产生，不接受模型孤立给出的页码作为唯一证据；
• 同一值存在多个候选时全部保留并标为 conflict。

P1-C：EvidenceRef 服务

关联问题：P1-10、P1-27。

• 新建 evidence.py 提供字段到 PDF 区域、表格单元格到字段的双向索引；
• 原文保存必要的最小片段和 hash，避免在日志中复制全文；
• 提供受鉴权的页面预览接口和证据定位接口；
• 证据状态包含 auto/confirmed/rejected/superseded。

建议 API：

• GET /api/insurance/documents/{id}
• GET /api/insurance/documents/{id}/pages/{page}
• GET /api/insurance/documents/{id}/pages/{page}/preview
• GET /api/insurance/plan-snapshots/{id}/evidence?fieldPath=...

Phase 1 出口门禁：每个关键金额具有真实页码和 bbox；同年份多场景不合并；跨页表在金标准中的行召回达到阶段阈值；服务端路径不出现在 API 响应。

Phase 2：候选合并、人工复核与金标准达标（P0，8～12 人日）

目标

让“正确性”取代“完整度”成为确认依据，并让用户真正具备核对能力。

任务包

P2-A：Extraction Candidate 与 Reconciliation

关联问题：P1-06、P1-07、P1-08、P1-09、P1-10、P1-14、P1-15。

• 正则、profile 表格提取、OCR、LLM 语义识别均输出候选，不直接覆盖最终值；
• 候选包含 raw_value、normalized_value、unit、currency、status、evidence[]；
• 文件名和所选产品只写入 context_hint；与 PDF 证据不一致时生成 conflict；
• 正则不再因为“有标签”自动压过 LLM/表格结果；由证据质量、profile 和业务校验统一评分；
• LLM 仅负责页面/表头语义、同义词和段落摘要，密集金额优先由表格解析产生；
• completeness 与 correctness 分开计算，存在关键冲突时最高只能 review_required。

P2-B：业务校验规则

关联问题：P0-02、P0-11、P0-12、P1-13、P1-26。

最少实现：

• 币种/单位一致；
• 保单年度与受保人年龄关系；
• 保证、非保证、总额公式（只在产品规则明确时启用）；
• 场景、提取前后和红利实现率隔离；
• 身故利益、退保价值、账户价值不可互代；
• 比较输入的年龄、性别、吸烟、保费、缴费期、保额、币种、附加险和提取方案兼容性；
• 口径不可比时允许并列展示，但禁止生成排名和“更优”结论。

P2-C：复核工作台

关联问题：P0-07、P1-27、P1-29。

• 把 PdfPagePreview.vue 抽成 PPT/海报共享证据预览组件；
• 宽屏使用 PDF、字段、完整利益表三栏；窄屏使用标签页，不隐藏关键校验状态；
• 点击字段定位 PDF 页和 bbox；点击 PDF 区域反向高亮候选字段；
• 完整利益表按 scenario_type 分组，支持逐行编辑、冲突比较和证据查看；
• 人工修改必须填写原因；modificationLog 通过后端持久化为 override，不再只存前端内存；
• 所有阻断项集中展示，确认按钮展示具体不可用原因。

Phase 2 出口门禁：30 份双人标注样本完成；关键标量精确率不低于 99.5%；金额单元格精确率和目标行召回率不低于 99.0%；同年多场景污染为 0；所有导出候选金额证据覆盖率 100%。未达门槛不得进入默认解析路径。

Phase 3：统一 PlanData Snapshot 与海报/PPT 投影（P0，6～9 人日）

目标

消除海报和 PPT 两套计划书事实，使任何修改、生成和历史记录都指向唯一快照。

任务包

P3-A：PlanData Schema 和不可变快照

关联问题：P0-01、P0-14、P0-15、P1-28、P1-29。

• 定义版本化 PlanData JSON Schema；
• 身份、保单、受保人、分场景利益、提领、附加险、假设、校验结果分区；
• 所有字段使用 FieldValue 或等价结构；
• 通过 document_id/snapshot_id 更新，不再按 pdfName 匹配；
• 确认、修改、撤销确认都创建新版本并保留 previous link；
• 快照 hash 使用规范化 JSON，写入历史和生成任务。

P3-B：海报 Projection

关联问题：P0-01、P0-05、P1-12、P1-14、P1-15。

• 删除海报独立紧凑解析在新链路中的事实职责；
• extract_for_poster 仅在兼容开关下保留，标记 deprecated；
• 新建 plan_data/projections.py::to_poster_projection，里程碑值只从已确认完整表投影；
• 文案事实、产品手册规则和计划书事实分开传递，禁止互相覆盖；
• 海报渲染后抽取文本并与 projection 对账。

P3-C：PPT DeckContract Projection

• Normalizer 改为纯 PlanData -> DeckContract 转换，不做业务猜测；
• DeckContract 保留字段状态、币种、单位和 evidence id；
• 图表只接收可比较且已确认的 series；
• 不允许渲染器自行推导缺失值。

P3-D：旧数据策略

• 旧记录只读展示；
• 需要重新生成时提示“需使用当前解析器重新解析并确认”；
• 不自动把旧 confirmed_data 转为可信快照；
• 可将旧数据导入 draft candidate，但状态必须是 review_required。

Phase 3 出口门禁：同一 snapshot 的海报和 PPT 基础字段、币种、10/20/30 年值一致率 100%；任何修改生成新版本；成品可追溯到唯一 snapshot hash。

Phase 4：PPT 场景、策略与模板可执行化（P0/P1，8～12 人日）

目标

让后台配置真实、确定地控制 PPT 的业务页面、比较规则和视觉承载。

任务包

P4-A：ScenarioDefinition 与服务端解析器

关联问题：P0-08、P0-09、P0-10、P1-19、P1-25、P2-02、P2-03。

• 实现场景 selector：文件数量、险种/产品/公司组合和客户条件；
• 实现 pageSpecs、metricSpecs、comparisonYears、fallback；
• 前端删除硬编码场景检测，只展示服务端 /resolve-scenario 结果；
• 用户明确选择已发布场景时优先；不兼容则阻断，不静默改为硬编码场景；
• 多个同优先级命中或无匹配时阻断并返回 matchTrace；
• 后台补齐编辑、复制版本、校验、发布、停用和规则试跑。

P4-B：GenerationPolicy

关联问题：P1-26。

• 明确兼容性、计算、缺失、排名、结论、阻断和降级策略；
• 不同口径只能并列展示时，在 pageSpec 中使用 nonComparableReason；
• IRR、倍数和排名所用公式、输入字段和精度必须版本化；
• 不允许策略写回或修改 PlanData。

P4-C：TemplateDefinition 与发布门禁

关联问题：P1-22、P1-23、P1-24、P2-04、P2-08。

• 每种 page_type 定义语义槽位、容量、溢出规则和样本；
• 上传 PPT 后校验必需 page_type、slot、唯一映射、字体、图表和页容量；
• 取消页面匹配失败时静默取第一张未使用页面；
• clone_ready 改为校验结果，不得仅因文件能打开就设为 true；
• 不再无差别清除模板文本/图表/表格；只替换已声明的业务 slot；
• 风格选项要么提供真实独立主题，要么合并重复选项，避免后台虚假差异。

P4-D：唯一合并规则

运行时顺序固定为：

1. 解析并冻结 ScenarioDefinition；
2. 使用 pageSpecs 形成业务页面清单；
3. 验证 GenerationPolicy；
4. 将 page_type 映射到 TemplateDefinition slot；
5. 无槽位或容量超限则阻断；
6. 生成 DeckContract；
7. 渲染器严格按合并结果执行。

不得再以 scenarioSlides or slidesConfig 这种隐式优先级决定业务逻辑。

Phase 4 出口门禁：修改场景比较年份和 pageSpecs 后样本输出按新版本变化；修改模板映射后页面顺序变化；不兼容输入可解释地阻断；同输入同版本结构确定；发布配置应用测试 100% 通过。

Phase 5：冻结任务输入、输出对账与任务可靠性（P0，6～9 人日）

目标

保证提交时预览、Worker 实际输入和最终成品一致，并让错误成品无法显示为成功。

任务包

P5-A：完整输入冻结

关联问题：P0-14、P0-15、P1-20、P1-21。

任务创建时冻结：

• PlanData 内容、ID、版本、hash；
• 源 PDF hash；
• ScenarioDefinition 内容、版本、hash；
• GenerationPolicy 内容、版本、hash；
• TemplateDefinition 内容、版本、hash 和源资产 hash；
• renderer version；
• 用户选择、人工覆盖记录、brand policy；
• 提交时 draft_revision。

Worker 只读 input_snapshot_json 或不可变版本记录，不查询当前 session.extractions_json、当前模板配置或当前场景。完成时使用 submit_revision：若会话已变化，则标记 stale，不得把 generated_revision 写成当前草稿版本。

P5-B：PPTX 数值对账

关联问题：P0-16。

• 生成后解析 PPTX XML；
• 校验所有可见金额文本、表格单元格和图表 series；
• 对账键至少包含 field_path/page_type/series/category/currency/value；
• 区分格式化差异与数值差异；
• P0 数值缺失、多余、币种错误或冲突直接失败；
• 失败任务保留诊断报告，不提供成功下载入口。

P5-C：海报数值对账

• 对 render document 和最终 DOM/导出文本做字段清单对账；
• AI 背景不得包含业务文字；
• 导出尺寸、裁切、文本溢出和空模块纳入门禁。

P5-D：任务心跳、幂等与重试

关联问题：P2-05、P2-06。

• Worker 定期更新 heartbeat_at；超时判断使用心跳而非创建时间；
• 幂等键包含 artifact type、snapshot hash、scenario/template/renderer hash；
• 重试复用同一冻结输入，禁止重试时重新解析或重新选模板；
• 旧 parse_worker.py 明确标记 deprecated，确认无引用后单独删除，不与主修复混改。

Phase 5 出口门禁：排队期间修改会话或后台配置不改变已提交任务；PPT/海报所有输出金额对账 100%；任何 P0 对账失败都不会产生可下载成功成品；任务可按冻结输入重放。

Phase 6：监控、隐私、灰度与正式切换（P1/P2，5～7 人日）

目标

让准确率、异常和数据生命周期持续可管理，并安全替换旧链路。

任务包

P6-A：质量看板与结构化日志

关联问题：P2-07。

解析指标：

• 文档 hash、PDF 类型、页数、profile 和版本；
• 原生/OCR 页数、耗时、字段候选数、冲突数；
• 表格数、跨页表数、未识别列数；
• 自动通过、人工修改、阻断数量和按字段修改率。

生成指标：

• snapshot/scenario/policy/template/renderer 版本与 hash；
• matchTrace、页面类型、降级、对账和视觉检查；
• 队列时间、执行时间、心跳、重试和最终状态。

指标需可按保险公司、产品、版式、PDF 类型和解析版本聚合。

P6-B：隐私、访问与清理

关联问题：P1-17、P1-30。

• PosterCaseUpload.to_dict() 不再返回服务器绝对路径；
• PDF 仅通过鉴权预览/下载接口访问；
• 日志禁止写原始全文、完整客户身份和大段解析内容；
• 为源 PDF、IR、候选、快照、证据、海报、PPT 和日志分别配置留存期；
• 到期清理同时覆盖数据库和对象文件，并留下脱敏审计；
• 金标准集仅使用获批脱敏样本。

P6-C：双轨灰度与切换

• 功能开关建议：DOCUMENT_IR_V1、PLAN_SNAPSHOT_V1、SCENARIO_ENGINE_V2、OUTPUT_RECONCILIATION_V1；
• 先影子解析，不影响用户输出；比较新旧字段并记录差异；
• 达到金标准门槛后按保司/profile 灰度到 10% -> 30% -> 100%；
• 新链路稳定后关闭紧凑解析和旧场景检测的默认入口；
• 旧链路仅作为短期只读回放，不允许产生新成品。

Phase 6 出口门禁：指标、报警、权限和清理任务可验证；100% 流量切换后连续观察期无 P0 对账错误；旧写路径关闭；应急回滚可在不丢失新快照的情况下执行。

7. API 改造清单

7.1 文档与证据

方法	路径	用途	关键约束
POST	/api/insurance/documents	统一上传并创建 Document	返回 documentId，不返回绝对路径
GET	/api/insurance/documents/{id}	文档状态和质量	仅所有者/授权角色可见
GET	/api/insurance/documents/{id}/pages/{page}/preview	PDF 页预览	鉴权、限时、可审计
GET	/api/insurance/documents/{id}/tables	表格和跨页关系	支持 scenario/page 过滤
POST	/api/insurance/documents/{id}/extract	创建解析任务	接收 profile hint，不允许覆盖文档事实

7.2 PlanData 与复核

方法	路径	用途	关键约束
GET	/api/insurance/plan-snapshots/{id}	获取快照与校验结果	返回 schemaVersion、hash、status
GET	/api/insurance/plan-snapshots/{id}/evidence	查询字段证据	fieldPath 必填或分页
PATCH	/api/insurance/plan-snapshots/{id}/draft	编辑草稿	乐观锁 + overrideReason
POST	/api/insurance/plan-snapshots/{id}/validate	执行业务校验	不改变 confirmed 版本
POST	/api/insurance/plan-snapshots/{id}/confirm	生成确认版本	冲突为零、关键证据齐全
GET	/api/insurance/plan-snapshots/{id}/poster-projection	海报只读投影	不允许调用端覆盖事实
GET	/api/insurance/plan-snapshots/{id}/deck-contract	PPT 只读投影	返回可比较性和缺失状态

7.3 场景与模板

方法	路径	用途
POST	/api/insurance/ppt/scenarios/resolve	基于 snapshot 列表返回唯一场景和 matchTrace
POST	/api/insurance/admin/ppt/scenarios/{code}/versions	创建 draft 版本
POST	/api/insurance/admin/ppt/scenario-versions/{id}/validate	使用样本试跑
POST	/api/insurance/admin/ppt/scenario-versions/{id}/publish	发布不可变版本
POST	/api/insurance/admin/ppt/template-versions/{id}/validate	校验 page_type、slot、容量和样本渲染
POST	/api/insurance/admin/ppt/template-versions/{id}/publish	发布模板版本

7.4 生成

现有 PPT/海报生成入口保留，但请求改为携带 snapshotId、可选的已发布 scenarioVersionId 和 templateVersionId。响应和任务详情新增：

• submitRevision、snapshotHash；
• scenarioVersion、policyVersion、templateVersion、rendererVersion；
• matchTrace、reconciliationStatus、visualCheckStatus；
• resultState=current|stale|failed。

错误码至少区分：数据未确认、证据不足、存在冲突、场景多匹配、场景不匹配、模板槽位缺失、输入不兼容、输出对账失败、视觉门禁失败。

8. 前端实施计划

8.1 复核工作台

• PPT 与海报共用一个证据复核核心组件，业务外壳可分别保留；
• 显示字段状态：自动提取、人工确认、冲突、缺失、推导；
• 未知值显示 —，不预填 0；
• 金额编辑同步选择币种/单位，避免只改数字；
• 完整利益表按场景标签分组；
• 提交确认前展示阻断项数量、警告项数量和人工覆盖数量；
• 后端返回错误使用字段路径定位到具体控件。

8.2 PPT 生成页

• 删除本地场景计算，调用服务端 resolver；
• 展示最终场景、版本、命中规则和不可比较原因；
• 模板列表只显示服务端返回的兼容模板；
• 管理员/用户明确选择场景时，显示“已选择”而不是被后台替换；
• 历史成品展示数据、场景、模板版本以及 current/stale 状态。

8.3 管理后台

• 场景：选择规则、比较条件、指标、年份、页面、缺失/结论策略；
• 模板：page_type、semantic slot、容量、溢出规则、预览和校验报告；
• 发布前必须选样本集试跑；
• 已发布版本只读；编辑操作自动创建新 draft；
• 明确展示“验证失败不可发布”的原因。

8.4 可访问性和响应式

• 键盘可完成字段跳转、冲突选择、表格编辑和确认；
• 状态不能只依赖颜色；
• PDF bbox 高亮有文本说明；
• 小屏不强行三栏，使用固定操作栏和标签切换；
• 长表使用虚拟滚动或分页，但不得只加载里程碑行。

9. 测试与质量门禁

9.1 测试分层

层级	重点	必须覆盖
单元测试	数值语义、候选合并、业务规则、hash	0/None/非法值、场景隔离、币种/单位、公式
Schema 测试	Document IR、FieldValue、PlanData、配置版本	向后兼容、未知字段、版本拒绝
API 测试	上传、确认、覆盖、发布、生成	越权、绕过前端、乐观锁、错误码
金标准测试	真实 PDF 精确值和证据	标量、每个表格单元格、页码、bbox、场景
集成测试	PDF -> confirmed snapshot -> 海报/PPT	同快照一致、任务冻结、重放
输出对账	PPTX XML、海报 DOM/导出文本	文本、表格、图表 series、币种
视觉回归	页面图片差异和布局探针	溢出、遮挡、裁切、空图、字体
稳定性	队列、重试、并发、清理	心跳、幂等、旧版本、孤儿文件

9.2 金标准样本矩阵

• 原生文本、全扫描、混合 PDF；
• 单栏、多栏、横向页；
• 有线框/无线框表、合并表头；
• 单页表、跨页表、续页无表头；
• 中文、英文、中英混合；
• 储蓄、重疾、IUL；
• 同一年多场景、提取前后、不同演示利率；
• 正确文件名、错误文件名、无意义文件名；
• 加密、损坏、超长、OCR 模糊/倾斜/低对比度。

9.3 强制验收指标

指标	门槛	阻断级别
关键标量精确率	>= 99.5%	未达不得默认开启新解析
金额表格单元格精确率	>= 99.0%	未达不得默认开启新解析
目标利益行召回率	>= 99.0%	未达不得默认开启新解析
导出金额正确证据覆盖率	100%	单次任务失败
同年份不同场景污染	0	发布阻断
未解决冲突自动确认	0	确认阻断
未知值静默变 0	0	测试/发布阻断
海报与 PPT 同快照一致率	100%	发布阻断
PPT 与 DeckContract 数值一致率	100%	单次任务失败
已发布场景/模板应用测试	100%	配置发布阻断
生成物版本追溯率	100%	发布阻断

9.4 建议回归命令

pytest -q tests/ppt_poster_optimization_test.py \
  tests/ppt_template_asset_test.py \
  tests/ppt_task_lifecycle_test.py \
  tests/ppt_parse_route_test.py \
  tests/poster_render_document_test.py \
  tests/poster_render_validation_test.py \
  tests/user_product_material_test.py

pytest -q tests/plan_data_*_test.py tests/document_ir_*_test.py tests/output_reconciliation_*_test.py

cd frontend
npm run lint
npm run build

部署环境另行执行 LibreOffice/Office/WPS 打开验证和页面渲染对比；本地缺少 python-pptx 时不得把相应跳过项当作通过。

10. 发布、灰度与回滚

10.1 发布顺序

1. 上线 Phase 0 门禁和兼容代码；
2. 上线 migrate_036~037 与只写不读的 Document/Snapshot 基础设施；
3. 开启影子解析，旧链路继续服务，收集差异；
4. 达到金标准门槛后按 profile 小流量读取新快照；
5. 上线版本化场景/模板，但先只发布内置样本验证通过的版本；
6. 上线任务冻结和输出对账，先 warning 模式观察，再切 failure 模式；
7. 关闭旧紧凑解析、旧场景检测和旧任务可变读取；
8. 观察稳定后清理 deprecated 写路径。

10.2 回滚原则

• 数据迁移只增表/增列，业务回滚不删除新数据；
• 功能开关按 profile 或租户回退，不回写旧确认状态；
• 已生成的新快照和审计记录保留，可在修复后重放；
• 对账 failure 模式可临时回退到“阻断下载、允许内部预览”，不得回退为对外成功交付；
• 已发布配置不修改，通过切换当前版本指针回滚；
• 任何回滚都记录操作者、原因、版本和影响范围。

10.3 灰度停止条件

• 任一错误金额进入成品；
• 同一快照海报/PPT 值不一致；
• 新解析人工修改率显著高于基线；
• 场景多匹配、模板错配或任务输入漂移；
• 鉴权绕过、绝对路径泄露或清理误删；
• P95 解析/生成时延超过约定容量且无法通过限流缓解。

11. 工作量、人员与里程碑

11.1 粗略工作量

阶段	预计人日	主要角色
Phase 0 止损与基线	4～6	后端、前端、QA、业务 SME
Phase 1 Document IR	7～10	后端/PDF、QA
Phase 2 合并与复核	8～12	后端/PDF、前端、QA、业务 SME
Phase 3 统一快照与投影	6～9	后端、前端、QA
Phase 4 场景与模板	8～12	后端、前端、PPT、QA
Phase 5 冻结与输出门禁	6～9	后端、PPT/前端、QA
Phase 6 运营与切换	5～7	后端、运维、安全、QA
合计	44～65 人日	不含业务样本收集等待时间

建议配置：2 名后端（其中 1 名熟悉 PDF/PPTX）、1 名前端、1 名 QA、1 名兼职保险业务 SME、1 名兼职运维/安全。该配置下预计 7～10 个自然周；如果仅 1 名开发串行推进，应按阶段门禁排期，不压缩金标准标注和灰度观察。

11.2 里程碑

• M1：Phase 0 完成，已知高危错误停止扩散；
• M2：Document IR 和证据定位可用，30 份金标准建立；
• M3：海报/PPT 统一消费 confirmed snapshot；
• M4：后台场景和模板版本真实控制生成；
• M5：任务可重放，输出对账失败关闭；
• M6：全量切换、留存闭环、旧写路径关闭。

每个里程碑必须单独评审，不以“代码已合并”代替完成。

12. 风险、依赖与需要确认的业务决策

风险/决策	影响	处理方式
缺少获批真实 PDF	无法量化准确率	Phase 0 即启动脱敏和双人标注；样本不到位不发布新解析
不同保司版式差异大	通用解析准确率波动	profile + 通用回退；按 profile 灰度
bbox/表格 IR 数据量大	存储和查询成本	按页 JSON、压缩、分层留存、避免逐字符入库
OCR 成本与时延	队列拥塞	按页质量调度、预算和并发限制、心跳
业务公式口径不明确	校验误报或错误推导	所有公式进入版本化 GenerationPolicy，由 SME 签字
模板缺少语义槽位	无法自动适配旧资产	旧模板作为 draft，逐个补 slot 并样本验证
旧记录无法可靠迁移	历史再生成受限	旧记录只读；再生成前重新解析确认
失败关闭降低短期成功率	用户感知任务变“更容易失败”	明确错误原因，提供修复入口；不以错误成品换成功率
多版本系统增加管理成本	管理员操作复杂	只提供 draft/validate/publish 三步，不引入无需求的审批流

开发前需业务明确：

1. 各险种关键必填字段及合理范围；
2. 哪些公式可用于校验，哪些仅可作为提示；
3. 同类比较与跨类并列展示的兼容条件；
4. 非保证利益的情景命名、演示利率和提取前后口径；
5. 源 PDF、快照、成品和日志的留存天数；
6. 金标准样本的授权、脱敏和双人复核负责人。

13. 问题覆盖矩阵

审计编号	计划任务	解决方式	验收位置
P0-01	P3-B/P3-C	海报/PPT 共用 confirmed snapshot	Phase 3
P0-02	P1-A/P1-B/P2-B	版面 IR、表格和业务校验	Phase 2
P0-03	P1-B	复合行键保留场景	Phase 1
P0-04	P1-B	跨页表连续性识别	Phase 1
P0-05	P0-A/P3-B	收紧回退并删除独立事实解析	Phase 3
P0-06	P0-A	后端确认 schema 和冲突门禁	Phase 0
P0-07	P2-C	PDF、字段、完整表并排复核	Phase 2
P0-08	P0-C/P4-D	临时诚实提示 + 唯一合并规则	Phase 4
P0-09	P0-C/P4-A	服务端场景解析与 matchTrace	Phase 4
P0-10	P4-A/P4-B	可执行场景和生成策略	Phase 4
P0-11	P0-B/P2-B	nullable/FieldValue 语义	Phase 2
P0-12	P0-B	删除错误字段兜底	Phase 0
P0-13	P0-B	统一币种格式化	Phase 0
P0-14	P3-A/P5-A	快照与完整任务冻结	Phase 5
P0-15	P5-A	使用 submit_revision 标记结果	Phase 5
P0-16	P5-B/P5-C	输出数值对账失败关闭	Phase 5
P0-17	P0-D/P2	真实 PDF 金标准	Phase 2
P1-01	P1-A	按页处理，取消全文硬截断	Phase 1
P1-02	P1-A	OCR 按页质量和预算调度	Phase 1
P1-03	P1-A	版面质量触发 OCR	Phase 1
P1-04	P1-B/P2-A	强 schema + 表格优先	Phase 2
P1-05	P1-C	真实 bbox 证据	Phase 1
P1-06	P2-A	候选合并，不静默覆盖	Phase 2
P1-07	P2-A	文件名仅作为 context hint	Phase 2
P1-08	P0-A/P2-A	产品选择只参与冲突检测	Phase 2
P1-09	P2-A/P2-B	correctness 与 completeness 分离	Phase 2
P1-10	P1-C	字段级 EvidenceRef	Phase 1
P1-11	P1-A	完整版本化缓存键	Phase 1
P1-12	P0-B	显式 None 判断	Phase 0
P1-13	P0-B/P2-B	禁止推导值冒充合同值	Phase 2
P1-14	P0-B/P3-B	字段语义统一	Phase 3
P1-15	P0-B/P2-A	冲突替代覆盖	Phase 2
P1-16	P0-A	PDF 产品一致性门禁	Phase 0
P1-17	P6-B	鉴权接口替代绝对路径	Phase 6
P1-18	P0-C	全产品满足模板条件	Phase 0
P1-19	P4-A	删除前端硬编码场景	Phase 4
P1-20	P0-C/P5-A	稳定排序并冻结实际模板	Phase 5
P1-21	P5-A	保存实际模板版本	Phase 5
P1-22	P4-C	仅替换语义槽位	Phase 4
P1-23	P4-C	页面无法匹配即阻断	Phase 4
P1-24	P4-C	validate/publish 门禁	Phase 4
P1-25	P4-A	comparisonYears 可配置	Phase 4
P1-26	P2-B/P4-B	完整兼容策略	Phase 4
P1-27	P1-C/P2-C	PDF 双向定位	Phase 2
P1-28	P3-A	document/snapshot ID 更新	Phase 3
P1-29	P2-C/P3-A	后端持久化 override	Phase 3
P1-30	P6-B	全链路留存和清理	Phase 6
P2-01	P0-A	parsed 与 confirmed 状态分离	Phase 0
P2-02	P4-A	完整场景版本编辑	Phase 4
P2-03	P0-C/P4-A	前端能力与文案一致	Phase 4
P2-04	P4-C	真实主题或合并重复风格	Phase 4
P2-05	P5-D	旧 Worker 退役	Phase 5
P2-06	P5-D	心跳超时	Phase 5
P2-07	P6-A	解析质量看板	Phase 6
P2-08	P0-D/P4-C/P5	视觉回归和输出门禁	Phase 5

14. Definition of Done

只有同时满足以下条件，本次全链路修复才算完成：

• 55 项审计问题均有关闭证据或经批准的延期记录；
• 30 份以上真实脱敏样本金标准通过，关键指标达到第 9.3 节门槛；
• 海报和 PPT 不再独立解析同一计划书事实；
• 所有新生成任务只接受 confirmed snapshot；
• 未知、冲突和推导值不会静默作为真实 0 或合同值输出；
• 后台场景、策略和模板均经过版本化发布与样本验证；
• Worker 不读取提交后的可变会话、场景和模板状态；
• PPT/海报成品数值对账 100%，P0 差异失败关闭；
• API 不暴露服务器绝对路径，源文件访问有鉴权；
• 源 PDF、IR、快照、证据、成品和日志留存清理经过 dry-run 与实删验证；
• 前端 lint/build、后端单元/集成/金标准/输出对账/视觉回归全部通过；
• 灰度、回滚、监控和运维手册已完成并演练；
• 相关 API、数据字典、测试用例和用户操作文档同步更新。

15. 建议立即启动的首个迭代

首个迭代只做以下内容，避免同时开太多架构分支：

1. 完成 P0-A：海报后端确认/生成门禁及绕过前端测试；
2. 完成 P0-B：None/0、错误字段兜底、币种的止损修复；
3. 完成 P0-C：模板全量适用条件、稳定排序和后台提示；
4. 建立 10 份开发金标准、标注规范和批量评测脚本；
5. 评审并冻结 Document IR、FieldValue、PlanData Snapshot 三份 schema，再开始 migrate_036~037。

首个迭代结束时必须提供：变更清单、测试证据、10 份样本基线、未解决冲突清单、下阶段 schema 评审记录。没有这些产出，不进入 Document IR 开发。

16. 与既有文档的关系

• PDF计划书解析后续演进详细计划_20260802.md：作为 parser profile、金标准和未知保司接入的详细参考；本计划补充统一快照及海报/PPT 消费边界。
• 海报生成工作台完整重构修复计划.md：作为海报画布、资产、导出和工作台交互参考；事实模型统一改用本计划 PlanData Snapshot。
• 保险智能客服系统_PPT与海报优化修复计划书_20260731.md：作为已完成/历史专项修复记录；新发现的配置覆盖和可复现性问题以本计划为准。
• PPT与海报编辑体验及解析问题专项优化修复计划书_20260731.md：继续作为局部 UI 与编辑体验参考；确认门禁、证据和版本规则以本计划为准。
• PPT多文件上传比对功能_详细修复计划书.md：继续作为上传和多文件交互参考；比较兼容性和场景解析迁移到 ScenarioDefinition/GenerationPolicy。

本计划不删除或覆盖既有文档，通过统一的阶段门禁和问题覆盖矩阵把它们纳入同一实施路线。