海报确认、文案生成、海报生成增加服务端失败关闭门禁，绑定文件哈希、解析快照哈希和确认数据哈希，并返回 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

46 KiB

Raw Blame History

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

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

1. 结论与实施决策

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

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

运行时顺序固定为：

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

不得再以 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 发布顺序

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

开发前需业务明确：

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

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. 建议立即启动的首个迭代

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

完成 P0-A：海报后端确认/生成门禁及绕过前端测试；
完成 P0-B：None/0、错误字段兜底、币种的止损修复；
完成 P0-C：模板全量适用条件、稳定排序和后台提示；
建立 10 份开发金标准、标注规范和批量评测脚本；
评审并冻结 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。

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

46 KiB Raw Blame History Unescape Escape