baodan/docs/PDF计划书解析后续演进详细计划_20260802.md

# PDF 计划书解析后续演进详细计划

> 文档版本：v1.0  
> 编制日期：2026-08-02  
> 适用范围：客户计划书 PDF 的解析、核对、PPT/PDF 生成、多保司展示与脱敏  
> 当前基线：已完成 15 份真实计划书专项修复和回归验证  
> 计划性质：后续开发执行基线，不替代现有需求、接口和部署文档

---

## 一、结论

后续目标不是继续为每份 PDF 堆叠硬编码，而是建立一条可持续的新保司接入链路：

```text
通用解析
→ 解析画像匹配
→ 确定性字段与表格抽取
→ 质量校验
→ AI 仅补缺失字段
→ 人工核对
→ 金标回归
```

解析规则采用“后台可编辑的声明式解析画像 + 版本化发布”。管理员可以在后台修改匹配条件、字段标签、表格列映射、情景选择和校验规则；系统负责用样本验证，只有测试通过的版本才能发布。用户或管理员对某次识别结果的修正只进入纠错队列，不会未经审核自动修改全局规则。

这样可以达到三个目的：

1. 同结构的新文件直接复用，不再逐份改代码；
2. 新保司首次接入只需准备样本、确认列映射和验收结果；
3. 无法确认的金额进入 `needs_review`，不以错误结果继续生成。

完整核心阶段预计 **15～18 人日**，其中后台画像管理、纠错审核、版本发布和回滚属于必做范围。

---

## 二、当前基线

### 2.1 已具备能力

| 能力 | 当前实现 | 结论 |
|------|----------|------|
| 混合文本/OCR | `api/insurance/ppt/extraction.py` | 可按页判断低质量文本并 OCR，表格 OCR 使用 PSM 4 |
| 通用字段 | `api/insurance/ppt/regex_extractor.py` | 支持年龄、性别、吸烟、币种、保费、保额、缴费期 |
| IUL 表格 | 同上 | 支持年度/年龄斜杠、独立列、纵向压缩和保证/非保证双栏 |
| 储蓄险表格 | 同上 | 支持身故利益与退保价值跨页合并 |
| 坐标表格 | `extract_iul_layout()` | 可处理 PyMuPDF 能直接识别的矢量表格 |
| 结果质量门禁 | `extraction.py`、`validator.py` | 可阻止明显缺失和异常数据直接标记成功 |
| 产品先验 | 产品 JSON 配置、文件名提示 | 已覆盖 SIUL3、SBIUL2、GIUL3、FWD IF、AIA PIL2 等样本 |
| 多保司生成 | `routes.py`、`celery_tasks.py`、`renderer.py` | 一次任务可保留和渲染多个保司 |
| 脱敏 | `masking.py`、用户端接口 | 新任务使用后台配置的脱敏名称 |
| 人工核对 | `PptDataReview.vue` | 用户可修改解析结果后再生成 |

### 2.2 已验证样本范围

当前真实回归集共 15 份，包含：

- 宏利 SIUL3：5 年缴、10 年缴；
- 永明 SBIUL2：5 年缴、10 年缴，首年双倍保费；
- 全美 GIUL3：5 年缴、10 年缴；
- 富卫 IF：简体、英文、新加坡版、保额型与总保费型文件名；
- 友邦 PIL2；
- CL HISP+：单缴和 5 年缴；
- GE PLG4：单缴储蓄计划。

当前回归结果：产品、年龄、性别、非吸烟状态、币种、核心金额、缴费期及利益表均可进入可用状态。

### 2.3 当前边界

| 边界 | 表现 | 后续处理 |
|------|------|----------|
| 未知产品名称 | Logo 为图片或正文无标准名称时可能识别为通用标题 | 产品先验 + 画像别名 + 人工确认 |
| 新表格结构 | 列顺序和情景定义完全不同可能列错位 | 解析画像明确列映射和情景选择 |
| 文件名无约定 | 无法使用 `F-48-N-USD-S3m-5x` 等先验 | 正文抽取；缺失时进入核对 |
| 低清扫描 | OCR 可能丢失年度、负号、小数点 | 页面质量评分、金额一致性校验、精确解析 |
| 多情景表格 | 保证、当前假设及不同回报率并列 | 画像指定首选情景，不允许默认猜测 |
| 新产品特殊规则 | 首年双倍、分期提领、额外账户等 | 产品画像声明金额语义和校验规则 |

---

## 三、目标与非目标

### 3.1 核心目标

| 编号 | 目标 | 验收指标 |
|------|------|----------|
| G-01 | 已登记产品稳定回归 | 金标关键字段准确率 ≥ 99%，不得出现高置信度错误金额 |
| G-02 | 同版式新文件自动复用 | 已有画像命中率 ≥ 95% |
| G-03 | 新保司可快速接入 | 1～2 份代表样本可在 0.5～1 人日内形成首版画像 |
| G-04 | 未知模板安全降级 | 关键金额不确定时状态必须为 `needs_review` 或 `partial` |
| G-05 | 结果可追溯 | 核心字段至少记录来源页、来源类型和置信度 |
| G-06 | 可持续测试 | 每新增一个产品，必须同时新增金标夹具和回归结果 |
| G-07 | 多保司与脱敏不回退 | 双保司生成、前端展示、导出结果保持一致并使用脱敏名称 |

### 3.2 首期非目标

- 不承诺对任意 PDF 达到 100% 无人工识别；
- 不让 LLM 直接生成或推算利益表金额；
- 不建设通用低代码 OCR 平台；
- 不允许自动把用户修正直接发布为全局规则；
- 不把完整客户 PDF 或敏感字段提交到公共代码仓库；
- 不同时重构现有 PPT、海报和推荐模块的无关代码。

---

## 四、目标架构

```mermaid
flowchart TD
    A["上传客户计划书"] --> B["文件安全检查与页级文本质量评分"]
    B --> C["产品先验与解析画像匹配"]
    C --> D["通用字段抽取"]
    C --> E["画像驱动的表格抽取"]
    D --> F["字段合并与来源记录"]
    E --> F
    F --> G["金额、年度、情景和险种质量校验"]
    G -->|通过| H["success / 可进入数据核对"]
    G -->|缺少语义字段| I["AI 定向补全缺失字段"]
    G -->|金额或列映射不确定| J["needs_review / 阻止直接生成"]
    I --> G
    J --> K["人工核对并保存修正"]
    K --> L["形成金标结果"]
    L --> M["新增或修订解析画像并跑全量回归"]
```

### 4.1 匹配优先级

解析画像按以下优先级匹配：

1. 用户已选择的 `productId`；
2. 产品标准名和别名精确匹配；
3. 文件名前缀或命名规则匹配；
4. 页内特征词、固定表头和公司标识组合匹配；
5. 无可靠匹配时使用通用解析器，状态不得伪装成已匹配产品。

禁止仅凭一个通用词，例如 `IUL`、`Premium`、`保单年度`，判定具体产品。

### 4.2 解析优先级

```text
明确的产品/用户先验
> 声明式解析画像
> 通用坐标表格
> 通用 OCR/正则表格
> AI 定向补字段
> 人工确认
```

金额字段发生冲突时，不以“最后写入者”为准，而是按照来源可信级别、标签明确度、表格完整度和一致性校验决定；无法决定时进入人工核对。

---

## 五、解析画像 v1

### 5.1 存储方案

后台可编辑意味着数据库必须保存草稿、发布版本和审计信息；代码仓库只保存 JSON Schema、内置种子画像和兜底默认值。

新增三类数据：

| 数据 | 用途 | 关键约束 |
|------|------|----------|
| `insurance_ppt_parser_profiles` | 画像主记录，关联保司、产品、险种和当前发布版本 | 一个产品可有多个版式画像；主记录不可直接保存未发布规则 |
| `insurance_ppt_parser_profile_versions` | 每次草稿、测试、发布和归档的完整配置快照 | 已发布版本不可原地修改，只能新建版本 |
| `insurance_ppt_parser_corrections` | 保存某次识别原值、人工修正值、差异和审核状态 | 修正不会自动修改画像；管理员审核后才能转成新草稿 |

建议字段：

```text
parser_profiles
├── id / name / company_id / product_id / plan_type
├── status / active_version_id
├── created_by / updated_by
└── created_at / updated_at / deleted_at

parser_profile_versions
├── id / profile_id / version
├── status: draft/testing/published/rejected/archived
├── config_json / test_report_json
├── created_by / tested_by / published_by
└── created_at / tested_at / published_at

parser_corrections
├── id / session_id / pdf_hash
├── product_id / profile_id / profile_version
├── original_data_json / corrected_data_json / diff_json
├── status: pending/ignored/applied
├── submitted_by / reviewed_by / applied_version_id
└── created_at / reviewed_at
```

代码仓库保留：

```text
api/insurance/ppt/config/parser_profile.schema.json
api/insurance/ppt/config/parser_profiles_seed/*.json
```

运行规则：

- 数据库中的 `published` 版本是运行时唯一生效来源；
- 种子画像只用于初始化或灾难恢复，不覆盖后台已经发布的版本；
- Worker 按 `profile_id + version` 缓存，发布或回滚时主动失效；
- 历史解析结果保存实际使用的画像 ID 和版本，不随后台修改而变化；
- 删除画像采用停用或软删除，不破坏历史任务。

### 5.2 建议 Schema

```json
{
  "id": "sunlife-sbiul2",
  "version": 1,
  "status": "published",
  "companyId": "sunlife",
  "productIds": ["sunlife-sbiul2-iul"],
  "planType": "iul",
  "match": {
    "filenamePatterns": ["^SLS_SBIUL2_"],
    "requiredTextAny": ["SBIUL 2", "SunBrilliance Indexed Universal Life II"],
    "requiredHeadersAny": ["Policy Year", "保单年度"]
  },
  "identity": {
    "issueAgeLabels": ["Age", "年龄", "上一次生日年龄"],
    "smokerLabels": ["Smoking Status", "风险等级"],
    "currencyLabels": ["Currency", "货币"]
  },
  "benefitTable": {
    "rowFormat": "year_age_columns",
    "scenarioPreference": ["current", "non_guaranteed", "guaranteed"],
    "columns": {
      "policy_year": ["Policy Year", "保单年度"],
      "age": ["Age", "年龄"],
      "annual_premium": ["Premium Planned", "计划保费"],
      "account_value": ["Account Value", "账户价值"],
      "total_surrender_value": ["Surrender Value", "退保价值"],
      "death_benefit": ["Death Benefit", "身故赔偿"]
    }
  },
  "amountRules": {
    "firstYearPremiumMultiplierAllowed": true,
    "totalPremiumMustBeNonDecreasing": true
  },
  "acceptance": {
    "minimumBenefitRows": 20,
    "requiredMilestoneYears": [1, 5, 10, 20, 30]
  }
}
```

### 5.3 配置约束

- 只允许白名单字段，不执行配置中的 Python 或表达式；
- 正则表达式加载时限制长度，并在测试阶段编译；
- 每个画像必须有唯一 `id + version`；
- 画像必须声明适用险种和至少一个可靠匹配条件；
- `scenarioPreference` 必须显式配置；
- 列别名只解决表头差异，特殊计算继续由受测代码实现；
- 配置加载失败时跳过该画像并记录错误，不能阻断全部解析服务。

### 5.4 后台编辑能力

后台新增“解析画像”管理页，管理员可以编辑：

| 分区 | 可编辑内容 |
|------|------------|
| 基本信息 | 画像名称、保司、产品、险种、状态 |
| 匹配规则 | 文件名规则、产品别名、必含文本、排除文本、固定表头 |
| 身份字段 | 年龄、性别、吸烟、币种、保额、保费和缴费期标签 |
| 表格结构 | 行格式、表头行、年度/年龄列、金额列映射、跨页延续规则 |
| 情景选择 | 保证、当前假设、非保证或指定回报率的优先级 |
| 金额语义 | 年缴、首年应缴、总保费、保额、首年倍数和累计逻辑 |
| 校验规则 | 最小数据行、关键年度、累计保费单调性、金额范围和必填字段 |
| 测试样本 | 关联样本、预期字段、关键年度和最近测试结果 |

后台不直接开放任意 Python 代码。常用规则使用表单和下拉框；只有“高级匹配”允许受限正则，并在保存时编译和限制长度。

管理员工作流：

```text
创建画像或从已发布版本复制
→ 编辑草稿
→ 用当前样本试跑
→ 运行该画像全部样本
→ 运行全局基线回归
→ 查看字段差异和失败原因
→ 发布新版本
→ Worker 缓存失效
→ 新任务使用新版本
```

若发布后出现问题，管理员可点击“回滚”，将某个历史已发布版本重新设为当前版本；系统不删除失败版本，保留审计记录。

### 5.5 识别错误后的纠错闭环

现有能力只保存当前会话修正后的 `extractions_json`，无法反向改进解析规则。后续改为：

1. 用户或管理员在数据核对页修正字段；
2. 服务端保存原始值、修正值、字段差异、PDF 哈希和画像版本；
3. 当前会话立即使用修正值，不需要再次调用模型；
4. 后台“解析纠错”列表展示待审核记录；
5. 管理员判断是单份文件异常，还是画像规则缺陷；
6. 单份异常可标记“忽略/仅本次有效”；
7. 规则缺陷可一键复制当前画像为新草稿，并把差异作为修改建议；
8. 管理员明确修改列映射或字段规则；
9. 新版本通过关联样本和全局回归后发布；
10. 后续同结构文件直接使用新规则，不再依赖模型猜测。

模型只允许辅助生成“草稿建议”，不得自动发布、自动改列映射或覆盖已确认金额。

---

## 六、分阶段实施计划

## Phase 0：发布当前专项修复（0.5 人日，P0）

### 任务

- [ ] PARSE-NEXT-0001 执行迁移 `migrate_033.py`～`migrate_035.py`；
- [ ] PARSE-NEXT-0002 重启 API 与 Worker，确认使用新解析代码；
- [ ] PARSE-NEXT-0003 重新上传 15 份基线 PDF，不复用历史缓存；
- [ ] PARSE-NEXT-0004 验证双保司任务可选择并输出两家公司；
- [ ] PARSE-NEXT-0005 验证后台脱敏名称在用户端和新生成文件中一致；
- [ ] PARSE-NEXT-0006 保留上线前后解析耗时和错误日志。

### 完成标准

- 15 份样本均通过核心字段核对；
- 新生成任务不再出现仅保留第一家保司；
- 新生成任务不向普通用户显示后台已设置脱敏的全称；
- 回滚时可恢复旧镜像和数据库快照。

---

## Phase 1：建立金标样本和批量评测（1.5 人日，P0）

### 任务

- [ ] PARSE-NEXT-0101 定义脱敏样本清单格式；
- [ ] PARSE-NEXT-0102 为现有 15 份 PDF 保存预期核心字段；
- [ ] PARSE-NEXT-0103 保存 1、5、10、20、30 年的关键利益值；
- [ ] PARSE-NEXT-0104 新增批量解析评测脚本；
- [ ] PARSE-NEXT-0105 输出字段准确率、缺失率、误报率、行数和耗时；
- [ ] PARSE-NEXT-0106 将评测接入本地发布检查，不把客户原 PDF 提交到 Git；
- [ ] PARSE-NEXT-0107 建立样本访问权限、脱敏和保留规则。

### 建议文件

```text
scripts/tools/evaluate_plan_parsing.py
tests/fixtures/ppt_parse/manifest.schema.json
tests/fixtures/ppt_parse/expected/*.json
```

期望结果示例：

```json
{
  "caseId": "manulife-siul3-5pay",
  "sourceRef": "secure-fixture://manulife-siul3-5pay.pdf",
  "planType": "iul",
  "expected": {
    "productName": "Manulife SIUL 3",
    "age": 48,
    "gender": "female",
    "smoker": "no",
    "currency": "USD",
    "sumInsured": 3000000,
    "annualPremium": 80060,
    "premiumPaymentPeriod": 5,
    "benefitRowCountMinimum": 70
  },
  "milestones": {
    "10": {"totalSurrenderValue": 362594}
  }
}
```

### 完成标准

- 单条命令可完成全部样本评测；
- 报告能明确指出具体文件、字段、期望值和实际值；
- 任何已登记样本核心金额变化都会使评测失败；
- 测试输出不包含客户姓名、证件号或 PDF 全文。

---

## Phase 2：画像数据模型与解析运行时（3.5 人日，P0）

### 任务

- [ ] PARSE-NEXT-0201 新增画像、版本和纠错记录的幂等迁移；
- [ ] PARSE-NEXT-0202 新增三个模型及索引、状态约束和 `to_dict()`；
- [ ] PARSE-NEXT-0203 定义并校验解析画像 JSON Schema；
- [ ] PARSE-NEXT-0204 实现只读取 `published` 版本的画像加载器；
- [ ] PARSE-NEXT-0205 实现按 `productId`、别名、文件名和文本指纹匹配；
- [ ] PARSE-NEXT-0206 匹配结果返回 `profileId`、`profileVersion`、`matchedBy` 和 `confidence`；
- [ ] PARSE-NEXT-0207 把现有文件名提示迁移到首批种子画像；
- [ ] PARSE-NEXT-0208 将 IUL/储蓄险行格式和情景偏好改为画像参数；
- [ ] PARSE-NEXT-0209 保留现有通用解析器作为无画像兜底；
- [ ] PARSE-NEXT-0210 为画像冲突、损坏配置、停用版本和无匹配增加测试。

### 完成标准

- 现有 15 份样本无需依赖集中式文件名前缀代码即可通过；
- 同一 PDF 只能选择一个最高可信画像；
- 两个画像得分接近且无法确定时返回 `needs_review`；
- 草稿或测试中的版本绝不会被生产解析任务读取；
- 历史结果可以追溯到实际使用的画像版本；
- 数据库画像不可用时，通用解析器仍能返回可解释状态。

---

## Phase 3：管理员解析画像后台（3 人日，P0）

### 后台页面

新增“解析画像”菜单和独立页面，不与“产品小册子解析结果”混在一起。页面包含：

1. 画像列表：保司、产品、险种、当前版本、状态、最近测试；
2. 画像编辑器：匹配、身份字段、表格列、情景、金额语义、校验六个标签页；
3. 样本诊断：左侧 PDF，右侧文本质量、候选表头、识别结果和字段来源；
4. 测试报告：期望值、实际值、差异、失败字段和全局回归结果；
5. 版本记录：草稿、测试、发布、驳回、回滚和操作人。

### 后台 API

| 方法 | URL | 用途 |
|------|-----|------|
| GET | `/insurance/admin/ppt/parser-profiles` | 查询画像列表 |
| POST | `/insurance/admin/ppt/parser-profiles` | 创建画像和首个草稿 |
| GET | `/insurance/admin/ppt/parser-profiles/{id}` | 查询详情、版本和样本 |
| PUT | `/insurance/admin/ppt/parser-profiles/{id}/draft` | 保存草稿配置 |
| POST | `/insurance/admin/ppt/parser-profiles/{id}/samples` | 上传或关联测试样本 |
| POST | `/insurance/admin/ppt/parser-profiles/{id}/test` | 异步运行当前画像测试 |
| GET | `/insurance/admin/ppt/parser-profile-tests/{taskId}` | 查询测试进度和报告 |
| POST | `/insurance/admin/ppt/parser-profiles/{id}/publish` | 发布已通过测试的版本 |
| POST | `/insurance/admin/ppt/parser-profiles/{id}/rollback` | 回滚到指定已发布版本 |
| POST | `/insurance/admin/ppt/parser-profiles/{id}/disable` | 停用画像 |

### 发布门禁

- [ ] PARSE-NEXT-0301 实现画像 CRUD、草稿和版本接口；
- [ ] PARSE-NEXT-0302 实现样本上传、鉴权和安全存储；
- [ ] PARSE-NEXT-0303 实现 Celery 画像测试任务和进度查询；
- [ ] PARSE-NEXT-0304 实现当前样本、画像样本集和全局基线三级测试；
- [ ] PARSE-NEXT-0305 只有三级测试通过才允许发布；
- [ ] PARSE-NEXT-0306 实现发布、停用和回滚；
- [ ] PARSE-NEXT-0307 所有管理操作写入审计日志；
- [ ] PARSE-NEXT-0308 完成后台编辑器和测试报告页面；
- [ ] PARSE-NEXT-0309 权限限制为 `config_manage`；
- [ ] PARSE-NEXT-0310 增加接口、权限、并发发布和回滚测试。

### 完成标准

- 管理员可在不改代码的情况下创建和调整解析画像；
- 保存草稿不会影响线上解析；
- 测试失败时发布按钮不可用，并显示具体字段差异；
- 发布后新任务使用新版本，历史任务保持旧版本；
- 回滚后新任务立即使用指定旧版本；
- 普通用户无法访问画像、样本和测试报告。

---

## Phase 4：字段证据与纠错审核闭环（2.5 人日，P0）

### 任务

- [ ] PARSE-NEXT-0401 为产品、年龄、吸烟、保费、保额、缴费期记录来源页；
- [ ] PARSE-NEXT-0402 为表格记录来源页、情景和表头映射；
- [ ] PARSE-NEXT-0403 区分 `profile`、`layout`、`ocr_regex`、`llm`、`filename_hint`、`user_confirmed` 来源；
- [ ] PARSE-NEXT-0404 数据核对页提交时保存原始值、修正值和字段差异；
- [ ] PARSE-NEXT-0405 后台新增“解析纠错”待审核列表；
- [ ] PARSE-NEXT-0406 支持“仅本次有效”“忽略”“转为画像草稿”三种处理；
- [ ] PARSE-NEXT-0407 转为画像草稿时只生成修改建议，不自动发布；
- [ ] PARSE-NEXT-0408 金额冲突或情景不明确时阻止直接生成；
- [ ] PARSE-NEXT-0409 增加纠错权限、重复记录和审计测试。

### 状态规则

| 状态 | 条件 | 是否允许直接生成 |
|------|------|:----------------:|
| `success` | 必填字段齐全，金额和表格校验通过 | 是 |
| `partial` | 非关键字段缺失，核心金额可信 | 需用户确认 |
| `needs_review` | 核心金额冲突、情景不明确或画像冲突 | 否 |
| `error` | 文件损坏、无法读取或解析链路异常 | 否 |

### 完成标准

- 用户能够回答“这个金额来自哪一页、哪一列”；
- 当前任务保存修正后不需要再次调用模型；
- 管理员可以看到哪些产品、字段最常被修正；
- 单次修正不会污染其他产品或全局画像；
- 规则修正必须形成新版本并通过回归后发布。

---

## Phase 5：未知保司后台接入（2 人日，P1）

### 标准流程

1. 管理员选择保司和产品，上传 1～2 份代表计划书；
2. 系统生成页级文本质量、候选表头、列映射和情景诊断；
3. 模型可提供画像草稿建议，但不得自动启用；
4. 管理员确认产品、金额语义、情景和列映射；
5. 管理员录入或确认金标字段和关键年度；
6. 系统运行当前样本、产品样本集和全局回归；
7. 测试通过后管理员发布；
8. 后续同结构计划书复用该画像。

### 任务

- [ ] PARSE-NEXT-0501 后台样本诊断展示页面质量、表格、表头和样例行；
- [ ] PARSE-NEXT-0502 生成候选产品、险种和画像匹配得分；
- [ ] PARSE-NEXT-0503 生成未启用的画像草稿；
- [ ] PARSE-NEXT-0504 支持管理员确认金标字段和关键年度；
- [ ] PARSE-NEXT-0505 用至少一家未登记保司完成演练；
- [ ] PARSE-NEXT-0506 验证常规新产品接入不需要修改解析代码。

### 完成标准

- 新保司首轮诊断不依赖代码修改；
- 画像草稿必须经过人工确认和测试后才能发布；
- 模型不可直接覆盖管理员确认的列映射和金额；
- 常规新产品接入工作量控制在 0.5～1 人日。

---

## Phase 6：质量监控、性能与发布门禁（1.5～2 人日，P1）

### 任务

- [ ] PARSE-NEXT-0601 记录解析耗时、OCR 页数、画像命中和 LLM 调用次数；
- [ ] PARSE-NEXT-0602 记录 `success/partial/needs_review/error` 分布；
- [ ] PARSE-NEXT-0603 统计人工修改最多的产品和字段；
- [ ] PARSE-NEXT-0604 对文本 PDF 和扫描 PDF 分开统计成功率与 P95；
- [ ] PARSE-NEXT-0605 缓存键包含解析器版本和画像版本；
- [ ] PARSE-NEXT-0606 发布前执行单元测试、金标评测和双保司 E2E；
- [ ] PARSE-NEXT-0607 增加画像功能开关和回滚说明。

### 建议指标

| 指标 | 目标 |
|------|------|
| 已登记产品核心字段准确率 | ≥ 99% |
| 已登记产品画像命中率 | ≥ 95% |
| 关键金额高置信度误报 | 0 |
| 文本 PDF 解析成功率 | ≥ 98% |
| 扫描 PDF 解析成功率 | ≥ 90%，单独统计 |
| `needs_review` 后仍直接生成 | 0 |
| 多保司遗漏 | 0 |
| 已开启脱敏却显示全称 | 0 |

### 完成标准

- 每次画像发布都有可保存的测试报告；
- 指标下降时能定位到解析器版本、画像版本和产品；
- 关闭画像功能开关后可回退到当前通用解析链路；
- 缓存不会复用旧画像产生的过期结果。

---

## 七、文件级改动预估

### 7.1 后端

| 文件 | 操作 | 说明 |
|------|:----:|------|
| `api/insurance/db/migrate_036.py` | 新增 | 画像、版本和纠错记录三张表；如编号冲突则顺延 |
| `api/insurance/models/ppt_parser_profile.py` | 新增 | 画像主记录和版本模型 |
| `api/insurance/models/ppt_parser_correction.py` | 新增 | 识别修正、审核状态和应用版本 |
| `api/insurance/ppt/parser_profiles.py` | 新增 | Schema 校验、发布版本加载和画像匹配 |
| `api/insurance/ppt/config/parser_profile.schema.json` | 新增 | 后台和后端共用的白名单 Schema |
| `api/insurance/ppt/config/parser_profiles_seed/*.json` | 新增 | 现有产品的初始化画像，不覆盖后台版本 |
| `api/insurance/ppt/extraction.py` | 修改 | 接入画像、记录画像版本和来源 |
| `api/insurance/ppt/regex_extractor.py` | 修改 | 接收行格式、列别名和情景参数 |
| `api/insurance/ppt/validator.py` | 修改 | 增加画像期望、金额冲突和情景校验 |
| `api/insurance/ppt/parse_worker.py` | 修改 | 保存诊断元信息和解析版本 |
| `api/insurance/ppt/routes.py` | 修改 | 数据修正时创建纠错记录 |
| `api/insurance/admin/ppt_admin_routes.py` | 修改 | 画像、样本、测试、发布、回滚和纠错 API |
| `api/insurance/admin/ppt_admin_service.py` | 修改 | 管理业务、权限、审计和发布门禁 |
| `api/insurance/generation/celery_tasks.py` | 修改 | 异步运行画像样本和全局回归 |
| `scripts/tools/evaluate_plan_parsing.py` | 新增 | 批量金标评测 |
| `scripts/tools/inspect_plan_pdf.py` | 新增 | 新模板诊断与画像草稿 |

### 7.2 前端

| 文件 | 操作 | 说明 |
|------|:----:|------|
| `frontend/src/pages/admin/PptParserProfilesAdmin.vue` | 新增 | 画像列表、编辑、测试、版本和回滚 |
| `frontend/src/pages/admin/PptParserCorrectionsAdmin.vue` | 新增 | 待审核纠错、差异对比和转草稿 |
| `frontend/src/utils/ppt-admin-api.ts` | 修改 | 画像管理、测试任务和纠错接口 |
| `frontend/src/pages/components/ppt/PptDataReview.vue` | 修改 | 显示来源、置信度、画像和冲突信息 |
| `frontend/src/pages/components/ppt/PptParsing.vue` | 按需修改 | 展示画像匹配和解析阶段 |
| `frontend/src/utils/ppt-api.ts` | 按需修改 | 适配诊断元信息字段 |

### 7.3 测试

```text
tests/ppt_parser_profile_test.py
tests/ppt_parser_profile_match_test.py
tests/ppt_parser_profile_regression_test.py
tests/ppt_parser_evidence_test.py
tests/ppt_parser_unknown_template_test.py
tests/ppt_parser_profile_admin_api_test.py
tests/ppt_parser_profile_publish_test.py
tests/ppt_parser_correction_test.py
tests/ppt_multi_company_masking_e2e_test.py
```

现有 `PptProductsAdmin.vue` 的“小册子解析结果”用于维护产品卖点和产品规则，不能复用为客户计划书解析画像编辑器；两类配置在菜单、接口和数据模型上保持分离。

---

## 八、测试矩阵

### 8.1 单元测试

| 类别 | 必测场景 |
|------|----------|
| 画像加载 | 正常、缺字段、重复 ID、版本错误、非法正则 |
| 画像匹配 | productId、别名、文件名、文本指纹、冲突、无匹配 |
| 身份字段 | 中英文、繁简体、Non-Smoker、否、未知 |
| 金额 | 千位符、小数、S/P 文件名、单缴、首年双倍、零值 |
| 表格 | 斜杠年度、独立列、纵向压缩、跨页、双情景、多情景 |
| 质量门禁 | 年度断裂、累计保费下降、退保值列错位、金额冲突 |
| 版本发布 | 草稿隔离、测试失败阻断、并发发布、历史版本、回滚 |
| 纠错审核 | 单次有效、忽略、转草稿、跨产品隔离、审计记录 |

### 8.2 集成测试

- 15 份现有真实样本全量回归；
- 每个画像至少覆盖两种缴费方案或两份代表文件；
- 至少一份未知保司文本 PDF；
- 至少一份未知保司扫描 PDF；
- 至少一份故意缺少产品名称或吸烟状态的 PDF；
- 至少一份保证/非保证情景并列的 PDF；
- 两份不同保司计划书同时生成；
- 脱敏开启和关闭两种生成结果。

### 8.3 端到端测试

```text
上传两份不同保司计划书
→ 两份均完成解析
→ 数据核对页显示对应产品和来源
→ 用户修正一个低置信度字段
→ 选择兼容模板
→ 生成 PPT/PDF
→ 两家公司均出现
→ 脱敏名称与后台配置一致
```

---

## 九、新保司接入 Checklist

### 样本准备

- [ ] 至少提供 1 份完整计划书，建议提供 2 份不同缴费方案；
- [ ] 确认产品标准名、保司、险种和版本；
- [ ] 样本已获授权并完成必要脱敏；
- [ ] 人工标注核心字段和关键年度金额。

### 解析确认

- [ ] 明确年龄是投保年龄、上次生日年龄还是下次生日年龄；
- [ ] 明确吸烟定义和观察期；
- [ ] 明确金额是年缴、首年应缴、总保费还是保额；
- [ ] 明确利益表使用保证、当前假设还是指定回报率情景；
- [ ] 明确账户价值、现金价值和退保价值对应列；
- [ ] 明确首年双倍或非等额缴费规则；
- [ ] 明确利益表终止年龄和期望年度数量。

### 发布确认

- [ ] 新画像 Schema 校验通过；
- [ ] 新产品样本全部通过；
- [ ] 现有 15 份基线无回归；
- [ ] 后端自动化测试通过；
- [ ] 前端生产构建通过；
- [ ] 已记录画像 ID、版本和回滚方法。

---

## 十、发布与回滚

### 10.1 发布步骤

1. 备份数据库和当前镜像；
2. 发布代码与解析画像；
3. 如有迁移，先由 API 单实例执行；
4. 重启 API 和 Worker；
5. 清理或自然失效旧解析缓存；
6. 运行现有 15 份样本冒烟；
7. 运行双保司与脱敏 E2E；
8. 小流量开放，观察成功率和人工修改率；
9. 指标稳定后全量开放。

### 10.2 回滚条件

出现以下任一情况立即停止扩量：

- 核心金额高置信度识别错误；
- 已登记产品准确率低于发布前基线；
- 两份计划书遗漏任一保司；
- 脱敏开启后仍向普通用户显示全称；
- 解析失败率或 P95 耗时显著恶化；
- Worker 出现持续积压。

### 10.3 回滚方式

- 关闭解析画像功能开关，回到通用解析器；
- 回滚代码镜像；
- 恢复旧画像版本；
- 不回写、不删除用户已确认的历史数据；
- 数据库迁移优先采用向后兼容设计，避免紧急降级表结构。

---

## 十一、风险与应对

| 风险 | 影响 | 应对 |
|------|------|------|
| 画像过度绑定单份样本 | 同产品另一方案失效 | 至少两份代表文件；匹配用稳定表头而非坐标常量 |
| OCR 小数点或年度丢失 | 金额或行号错误 | 累计保费、年龄偏移和年度连续性校验 |
| 多情景选错 | 收益数据系统性错误 | 画像显式声明情景；不明确则 `needs_review` |
| 文件名先验错误 | 错产品或错金额 | 文件名只补明确字段；与正文冲突时要求核对 |
| LLM 覆盖确定性数值 | 正确金额被改错 | 确定性字段受保护；LLM 仅补缺失字段 |
| 用户修正污染全局规则 | 后续文件被错误影响 | 修正先作为金标候选，审核后再更新画像 |
| 样本包含客户隐私 | 合规风险 | 安全存储、访问控制、脱敏、禁止提交原 PDF |
| 配置错误影响全部产品 | 大面积回归 | 画像隔离、Schema 校验、全量基线和功能开关 |

---

## 十二、排期与里程碑

| 里程碑 | 阶段 | 工作量 | 交付物 |
|--------|------|:------:|--------|
| M0 当前修复上线 | Phase 0 | 0.5 人日 | 迁移、重启、15 份冒烟结果 |
| M1 可量化回归 | Phase 1 | 1.5 人日 | 金标清单、评测脚本和基线报告 |
| M2 画像运行时 | Phase 2 | 3.5 人日 | 数据模型、Schema、加载器和首批画像 |
| M3 后台可管理 | Phase 3 | 3 人日 | 编辑、样本、测试、发布、版本和回滚 |
| M4 纠错可复用 | Phase 4 | 2.5 人日 | 字段证据、纠错队列、审核和转草稿 |
| M5 新保司可接入 | Phase 5 | 2 人日 | 后台诊断、金标确认和新保司演练 |
| M6 可灰度上线 | Phase 6 | 1.5～2 人日 | 指标、缓存版本、发布门禁和回滚开关 |

推荐执行顺序：

```text
第一周：Phase 0 → Phase 1 → Phase 2
第二周：Phase 3 → Phase 4
第三周：Phase 5 → Phase 6 → 灰度验收
```

---

## 十三、完成定义

核心计划只有在以下条件全部满足后才能标记完成：

- 当前 15 份样本形成可重复执行的金标回归；
- 管理员可以在后台编辑解析画像，不需要修改代码；
- 画像具备草稿、测试、发布、历史版本和回滚流程；
- 现有产品不再依赖集中式文件名硬编码即可识别；
- 新保司可以通过后台诊断和声明式画像接入；
- 产品、金额和利益表结果均经过质量门禁；
- 无法确认的关键金额不会被标记为成功；
- 核心字段具备来源页、来源类型和置信度；
- 人工修正进入后台纠错队列，可转为新画像草稿，但不会未经审核污染全局规则；
- 双保司生成和脱敏 E2E 通过；
- 发布包含指标观察、功能开关和回滚方案；
- 文档、测试和画像版本与代码同步维护。

---

## 十四、与现有文档的关系

| 文档 | 关系 |
|------|------|
| `PDF实时解析提速与精准抽取方案.md` | 描述实时解析总体方案；本文承接真实样本修复后的后续演进 |
| `PPT_PDF解析与数据核对页面问题修复报告_20260730.md` | 提供解析和核对页面的历史根因证据 |
| `PPT多文件上传比对功能_详细修复计划书.md` | 负责多文件和多保司上传生成链路 |
| `用户上传产品小册子解析与留存实施计划.md` | 面向产品小册子；本文面向客户计划书，二者不得混用 |
| `保险智能客服系统_测试用例.md` | 后续应补充画像、未知模板、多保司和脱敏验收用例 |