# BaodanPPT 融合同步计划书

> 更新时间：2026-07-23
> 当前状态：**MVP 原生重构阶段**，综合完成度约 **55%～65%**

---

## 一、总体进度评估

| 模块 | 融合状态 | 完成度 | 优先级 |
|---|---|---:|:---:|
| 前端入口与导航 | 已接入 | 90% | - |
| Vue 原生 PPT 流程页面 | 已搭建（4 个组件） | 85% | - |
| 前端 API 封装 | 已接入主系统 `/insurance` | 90% | - |
| 后端 Blueprint 路由 | 已挂载（10 个端点） | 90% | - |
| 数据库模型 | 已新增（5 个模型） | 85% | - |
| 配置数据迁移 | 路径已验证正确，待执行迁移 | 75% | **P1** |
| PDF 解析 | 已有完整实现（含缓存） | 70% | **P1** |
| LLM 客户端 | 多供应商 + 限流 + 自动切换 | 75% | **P1** |
| 数据归一化/验证 | 三种产品类型完整支持 | 80% | **P1** |
| PPT 渲染 | 有回退渲染，未复用 baodanppt 渲染器 | 35% | **P0** |
| 公司知识库/产品匹配 | 已实现三级匹配策略 | 60% | **P2** |
| IRR 精算计算 | 已实现 Modified-Actuarial NPV | 80% | **P2** |
| 多产品 Bundle | 模型存在，流程未真正支持 | 20% | **P2** |
| 预览、队列、缓存、会话隔离 | 大多未迁移 | 15% | **P3** |

**结论**：如果目标是"页面可点、PDF 可上传、AI 可解析、生成一个基础 PPT"，接近可联调；如果目标是"复刻 baodanppt v3.1.x 的正式生成能力"，还差较多。

---

## 二、已完成的融合点

### 2.1 后端路由已挂到主系统

`insurance.ppt.routes` 已注册到主系统，统一前缀 `/insurance/ppt`。

```python
# api/insurance/routes.py
app.register_blueprint(ppt_bp, url_prefix="/insurance/ppt")
```

**说明**：当前方案已绕过 baodanppt 的 Bun API，改为 Flask 原生模块接管。

### 2.2 数据库模型已新增并注册

新增 PPT 会话表、公司表、产品表、模板表、Bundle 表：

- `PptSession` - PPT 生成会话
- `PptCompany` - 公司配置
- `PptProduct` - 产品配置
- `PptTemplate` - 模板配置
- `PptBundle` - 多产品组合

数据库初始化已导入模型，`create_all()` 能感知这些表。

### 2.3 后端 API 流程基本齐全

已实现 10 个接口，形成完整 MVP 闭环：

| 接口 | 功能 |
|---|---|
| `GET /ppt/health` | 健康检查 |
| `GET /ppt/render-options` | 获取渲染选项（公司/模板） |
| `POST /ppt/upload` | 上传 PDF |
| `POST /ppt/parse/<session_id>` | 触发 AI 解析 |
| `GET /ppt/session/<session_id>` | 获取会话状态 |
| `POST /ppt/chat/<session_id>` | AI 对话 |
| `POST /ppt/generate/<session_id>` | 生成 PPT |
| `GET /ppt/download/<session_id>` | 下载 PPT |
| `GET /ppt/validate/<session_id>` | 验证提取数据 |
| `POST /ppt/company-kb/match` | 匹配公司知识库 |

### 2.4 前端已从 iframe 改为 Vue 原生页面

实现了四步流程：上传 → 解析 → 生成 → 结果

相比原计划的 iframe 方案，优点是认证、UI、路由更统一；缺点是需要重做 baodanppt 原有前端能力。

### 2.5 前端路由与 API 已接入

- `/ppt` 路由已添加到 `router/index.ts`
- 桌面端和移动端侧边栏已有 `PPT生成` 入口
- `ppt-api.ts` 基于现有 `api` 实例，自动使用 `/insurance` baseURL

---

## 三、主要问题与风险

### ~~3.1 【阻断】配置迁移路径错误~~ ~~已验证~~

**~~问题~~**：经验证，`migrate_014.py` 中 `CONFIG_DIR` 路径计算**实际正确**

```python
# 当前代码
CONFIG_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "..", "baodanppt", "config")
# 从 api/insurance/db 往上三层：db -> insurance -> api -> 项目根目录
# 最终路径：项目根目录/baodanppt/config ✓
```

**验证结果**：
- 路径规范化后为 `baodanppt\config`
- 目录存在且包含 companies、products、templates、bundles 子目录
- 配置文件（如 aia.json、axa.json 等）可正常读取

**结论**：此问题不存在，迁移脚本路径正确。

### 3.2 【阻断】下载接口认证问题

**问题**：前端用 `window.open()` 打开下载链接，但后端有 `@jwt_required`

```javascript
// 前端当前实现
function downloadPpt() {
  const url = pptApi.getDownloadUrl(props.sessionId)
  window.open(url, '_blank')  // 不会自动带 Authorization header
}
```

**影响**：下载时会 401 未授权。

### 3.3 【阻断】PPT 渲染未复用 baodanppt 渲染器

**问题**：当前 `PptRenderer` 查找的脚本文件不存在

```python
# 当前查找
render_script = os.path.join(script_dir, "fast_pptx_renderer.py")
# 实际 baodanppt/scripts 里没有这个文件
```

**实际 baodanppt 渲染架构**：

```
baodanppt/src/
├── generation/
│   ├── pptx-generator.ts      # 主 PPT 生成器（20KB）
│   ├── composition-engine.ts   # 组合引擎（25KB）
│   └── marp-renderer.ts       # Marp 渲染器（13KB）
├── render/
│   ├── fast-pptx.ts           # 快速 PPTX 渲染（TypeScript）
│   └── normalized-deck.ts     # 归一化 Deck 格式
└── scripts/
    ├── slide_renderer.py      # Python 滑动渲染器
    └── render_*.py             # 各类渲染脚本
```

**关键发现**：
- `fast_pptx_renderer.py` 不存在，实际是 `fast-pptx.ts`（TypeScript）
- 主渲染逻辑在 TypeScript 中，不是 Python
- `slide_renderer.py` 存在但接口可能不匹配

**影响**：会回退到 `_render_basic()`，生成极简 PPT，内容非常简陋。

### 3.4 【重要】文档与代码不一致

**问题**：`docs/baodanppt集成计划.md` 推荐 iframe 方案，但代码已改为原生重构

**影响**：后续开发容易混乱，需要更新文档。

### 3.5 【重要】Bundle 多产品组合未打通

**问题**：`generate_ppt()` 只取第一个成功提取结果

```python
# 当前实现
for ext in extractions:
    if ext.get("status") == "success" and ext.get("data"):
        ext_data = ext["data"]
        break  # 只取第一个
```

**影响**：多产品上传后，仍只生成单产品 PPT。

### 3.6 【一般】前后端字段命名不一致

**问题**：后端返回 `chat_history`，前端定义为 `chatHistory`

**影响**：后续做聊天历史显示时会踩坑。

---

## 四、同步计划

### 阶段一：修复阻断问题（预计 2-3 天）

**目标**：打通端到端流程，实现 MVP 可联调

| 序号 | 任务 | 负责 | 验证标准 | 状态 |
|:---:|---|---|---|:---:|
| 1.1 | ~~修正 `migrate_014.py` 配置路径~~ | 后端 | ~~迁移后数据库有公司/产品/模板数据~~ | ✅ 已验证正确 |
| 1.2 | 确认 `MIGRATION_ENABLED` 配置或提供手动迁移方式 | 后端 | 可手动执行迁移脚本 | 待验证 |
| 1.3 | 修复下载接口，改为带 token 的 blob 下载 | 前端+后端 | 点击下载可正常获取文件 | 待修复 |
| 1.4 | 确认 `ppt_work`、`uploads`、`downloads` 目录可写 | 运维 | 目录存在且有写入权限 | 待验证 |
| 1.5 | 补充运行依赖：`PyMuPDF`、`python-pptx`、`httpx` | 后端 | `pip install` 成功 | 待验证 |
| 1.6 | 更新 `docs/baodanppt集成计划.md` 文档 | 文档 | 文档反映当前原生重构方案 | 待更新 |

### 阶段二：接通正式渲染（预计 3-5 天）

**目标**：生成可用的正式 PPT，而非极简回退版本

| 序号 | 任务 | 负责 | 验证标准 |
|:---:|---|---|---|
| 2.1 | 确定要复用的 baodanppt 渲染入口脚本 | 后端 | 明确 `slide_renderer.py` 或其他脚本 |
| 2.2 | 实现 Flask 归一化数据 → DeckContract 转换 | 后端 | 数据格式匹配渲染器要求 |
| 2.3 | 接通至少一个正式模板（如 `savings/business`） | 后端 | 生成的 PPT 有完整样式和内容 |
| 2.4 | 让 `theme`、`companyId` 影响模板与公司品牌 | 后端+前端 | 不同选择生成不同样式 PPT |
| 2.5 | 统一前后端字段命名（camelCase） | 前端+后端 | 接口返回和前端定义一致 |

### 阶段三：补齐核心能力（预计 5-7 天）

**目标**：达到 baodanppt 原有核心能力的 80%

| 序号 | 任务 | 负责 | 验证标准 |
|:---:|---|---|---|
| 3.1 | 多产品 Bundle 生成 | 后端 | 多 PDF 上传可生成组合 PPT |
| 3.2 | 公司知识库 evidence files 对接 | 后端 | 可加载公司专属知识 |
| 3.3 | 生成队列和状态轮询 | 后端 | 支持多任务并发生成 |
| 3.4 | 预览图/PDF 预览 | 前端+后端 | 生成后可在线预览 |
| 3.5 | 会话恢复与历史记录 | 前端+后端 | 可查看历史生成记录 |

### 阶段四：高级能力与优化（预计 7-10 天）

**目标**：完整复刻 baodanppt v3.1.x 能力

| 序号 | 任务 | 负责 | 验证标准 |
|:---:|---|---|---|
| 4.1 | 完整 PDF 解析流水线（公司证据校验、产品目录匹配） | 后端 | 解析准确率提升 |
| 4.2 | 会话隔离与缓存优化 | 后端 | 支持多用户并发 |
| 4.3 | 管理端配置维护界面 | 前端+后端 | 可在线管理公司/产品/模板 |
| 4.4 | 性能优化与错误处理完善 | 全栈 | 生成时间 < 30s，错误友好提示 |

---

## 五、联调检查清单

在阶段一完成后，按以下步骤验证：

```
[ ] 1. 启动 Flask API，访问 /insurance/ppt/health 返回正常
[ ] 2. 启动前端，访问 /ppt 页面显示正常
[ ] 3. 调用 /insurance/ppt/render-options，公司和模板列表不为空
[ ] 4. 上传 PDF 文件，返回 session_id
[ ] 5. 调用 /ppt/parse/<session_id>，解析成功
[ ] 6. 调用 /ppt/generate/<session_id>，生成 PPT 文件
[ ] 7. 点击下载，可正常获取 PPT 文件
```

**最可能卡住的地方**：

1. ~~`migrate_014.py` 没导入配置 → 公司列表为空~~ ✅ 已验证路径正确
2. LLM API key 未配置 → 解析失败
3. `PyMuPDF` / `python-pptx` 未安装 → 导入错误
4. 下载时 `Authorization` header 缺失 → 401
5. 渲染脚本找不到 → 生成极简 PPT（实际存在 `slide_renderer.py`，需确认接口）

---

## 六、技术决策记录

### 6.1 集成方案变更

| 原计划 | 当前方案 | 变更原因 |
|---|---|---|
| iframe 嵌入 baodanppt 前端 | Vue 原生四步页面 | 认证、UI、路由更统一 |
| Vite 代理 `/ppt-api` 到 Bun | Flask 原生 `/insurance/ppt/*` | 减少服务依赖 |
| Bun 服务继续运行 | 统一 Flask 后端 | 架构更简洁 |

### 6.2 待确认事项

1. **渲染入口**：确认使用 `slide_renderer.py` 还是其他脚本作为主渲染器
2. **模板格式**：确认 baodanppt 模板的 DeckContract 数据结构
3. **Bundle 规划**：确认多产品组合的优先级和实现方式

---

## 七、风险与应对

| 风险 | 影响 | 应对措施 |
|---|---|---|
| 渲染脚本接口不兼容 | 无法生成正式 PPT | 阶段二重点攻克，必要时重写适配层 |
| baodanppt 升级导致接口变化 | 已接通的功能失效 | 保持接口抽象，及时跟进上游变化 |
| 多产品 Bundle 复杂度高 | 开发周期延长 | 先保证单产品流程，Bundle 作为增强 |
| Windows 环境路径问题 | 本地开发受阻 | 使用 `pathlib` 统一路径处理 |

---

## 八、下一步行动

**立即执行（今天）**：

1. ~~修正 `migrate_014.py` 配置路径~~ ✅ 已验证正确
2. 测试配置迁移是否成功（执行 `migrate_014.py`）
3. 修复下载接口认证问题

**本周完成**：

1. 完成阶段一所有任务
2. 端到端联调通过
3. 更新相关文档

**下周目标**：

1. 接通正式渲染模板
2. 生成第一个可用的正式 PPT

---

## 九、验证结果记录（2026-07-23）

### 9.1 已验证正确的项目

| 项目 | 验证结果 | 说明 |
|---|---|---|
| 后端路由注册 | ✅ 正确 | `ppt_bp` 已注册到 `/insurance/ppt` |
| 数据库模型 | ✅ 正确 | `PptSession`、`PptCompany`、`PptProduct`、`PptTemplate`、`PptBundle` 已导入 |
| API 端点 | ✅ 正确 | 10 个端点与计划书一致 |
| 前端页面 | ✅ 正确 | Vue 原生四步流程已实现 |
| 前端 API 封装 | ✅ 正确 | `ppt-api.ts` 与后端路由匹配 |
| `migrate_014.py` 路径 | ✅ 正确 | 从 `api/insurance/db` 往上三层到达项目根目录，路径规范化后为 `baodanppt\config` |

### 9.2 已确认存在的问题

| 问题 | 严重度 | 状态 |
|---|---|---|
| 下载接口 `window.open()` 不带 Authorization header | 高 | 待修复 |
| 渲染脚本 `fast_pptx_renderer.py` 不存在 | 高 | 需确认使用 `slide_renderer.py` |
| 前后端字段命名不一致（`chat_history` vs `chatHistory`） | 中 | 待统一 |
| Bundle 只取第一个提取结果 | 中 | 待优化 |

### 9.3 待验证项目

| 项目 | 验证方法 |
|---|---|
| `MIGRATION_ENABLED` 配置 | 检查环境变量或配置文件 |
| `ppt_work`、`uploads`、`downloads` 目录权限 | 尝试写入测试 |
| `PyMuPDF`、`python-pptx`、`httpx` 依赖 | `pip list` 检查 |
| LLM API key 配置 | 尝试调用解析接口 |

---

## 附录 A：相关文件清单

### 后端文件

| 文件 | 说明 | 计划书提及 |
|---|---|:---:|
| `api/insurance/ppt/__init__.py` | 模块初始化 | ❌ |
| `api/insurance/ppt/routes.py` | 后端路由（10 个端点） | ✅ |
| `api/insurance/ppt/renderer.py` | PPT 渲染器 | ✅ |
| `api/insurance/ppt/extraction.py` | PDF 解析编排器 | ✅ |
| `api/insurance/ppt/llm_client.py` | 多供应商 LLM 客户端 | ✅ |
| `api/insurance/ppt/prompts.py` | 提取提示词模板 | ❌ |
| `api/insurance/ppt/normalizer.py` | 数据归一化（储蓄险/重疾险/IUL） | ❌ |
| `api/insurance/ppt/validator.py` | 数据验证（导出就绪检查） | ❌ |
| `api/insurance/ppt/irr.py` | IRR 精算计算模块 | ❌ |
| `api/insurance/ppt/knowledge.py` | 公司知识库匹配 | ❌ |
| `api/insurance/models/ppt_session.py` | 会话模型 | ✅ |
| `api/insurance/models/ppt_config.py` | 配置模型（公司/产品/模板/Bundle） | ✅ |
| `api/insurance/db/migrate_014.py` | 配置迁移脚本 | ✅ |

### 前端文件

| 文件 | 说明 | 计划书提及 |
|---|---|:---:|
| `frontend/src/pages/PptPage.vue` | 主页面（四步流程） | ✅ |
| `frontend/src/pages/components/ppt/PptUpload.vue` | 上传组件 | ❌ |
| `frontend/src/pages/components/ppt/PptParsing.vue` | 解析组件 | ❌ |
| `frontend/src/pages/components/ppt/PptGenerate.vue` | 生成组件 | ❌ |
| `frontend/src/pages/components/ppt/PptResult.vue` | 结果组件 | ✅ |
| `frontend/src/utils/ppt-api.ts` | API 封装 | ✅ |

### 文档

| 文件 | 说明 |
|---|---|
| `docs/baodanppt集成计划.md` | 原集成计划（需更新） |
| `docs/baodanppt融合同步计划书.md` | 本计划书 |

---

## 附录 B：环境变量配置

以下环境变量需要在 `.env` 或系统环境中配置：

| 变量名 | 用途 | 必需 |
|---|---|:---:|
| `DEEPSEEK_API_KEY` | DeepSeek LLM API 密钥 | 至少一个 |
| `MINIMAX_API_KEY` | MiniMax LLM API 密钥 | 至少一个 |
| `GEMINI_API_KEY` | Google Gemini API 密钥 | 至少一个 |
| `OPENAI_API_KEY` | OpenAI API 密钥（可作为 DeepSeek 备选） | 可选 |

**说明**：`llm_client.py` 会按 DeepSeek → MiniMax → Gemini 顺序尝试，至少需要配置一个 API Key。

---

## 附录 C：Python 依赖

| 包名 | 用途 | 必需 |
|---|---|:---:|
| `PyMuPDF` (fitz) | PDF 文本提取 | ✅ |
| `python-pptx` | PPT 生成 | ✅ |
| `httpx` | LLM API 调用 | ✅ |
| `flask` | Web 框架 | ✅ |
| `flask-sqlalchemy` | 数据库 ORM | ✅ |

安装命令：
```bash
pip install PyMuPDF python-pptx httpx
```

---

## 附录 D：模块功能详解

### D.1 数据归一化模块 (`normalizer.py`)

将 LLM 提取的原始数据转换为标准结构，支持三种产品类型：

| 函数 | 输入 | 输出 |
|---|---|---|
| `normalize_savings_plan()` | 储蓄险原始数据 | 标准化储蓄险结构 |
| `normalize_ci_plan()` | 重疾险原始数据 | 标准化重疾险结构 |
| `normalize_iul_plan()` | IUL 原始数据 | 标准化 IUL 结构 |
| `map_savings_metrics()` | 标准化储蓄险数据 | 关键指标（回本年度、倍数等） |

### D.2 数据验证模块 (`validator.py`)

检查归一化后数据的导出就绪性：

| 函数 | 验证内容 |
|---|---|
| `validate_formal_savings_plan()` | 储蓄险：产品名、年龄、保费、利益行数、连续性 |
| `validate_formal_ci_plan()` | 重疾险：保额、保费、保障项目 |
| `validate_formal_iul_plan()` | IUL：指数账户、利益行数、缴费年期一致性 |
| `validate_savings_metrics()` | 储蓄险关键指标完整性 |

### D.3 IRR 计算模块 (`irr.py`)

精算级 IRR 计算，符合 HK IA 监管要求：

| 函数 | 用途 |
|---|---|
| `compute_irr_ma()` | 基础 Modified-Actuarial NPV IRR |
| `compute_irr_ma_withdraw()` | 含退保场景的 IRR |
| `ia_irr_cap()` | 获取 HK IA 监管上限（HKD 6.0%，其他 6.5%） |

### D.4 公司知识库模块 (`knowledge.py`)

匹配公司和产品，支持多级匹配策略：

| 匹配策略 | 说明 |
|---|---|
| 强制指定 | 直接指定公司 ID |
| 产品目录匹配 | 通过产品别名查找对应公司 |
| 别名/标签模糊匹配 | 基于公司别名的模糊匹配 |

### D.5 LLM 客户端 (`llm_client.py`)

多供应商自动切换 + 限流保护：

| 特性 | 说明 |
|---|---|
| 供应商顺序 | DeepSeek → MiniMax → Gemini |
| 限流保护 | Token Bucket 算法，自动排队 |
| 失败切换 | 一个供应商失败自动切换下一个 |
| 统一接口 | `chat()` 简单聊天，`structured_output()` 结构化输出 |

---

## 附录 E：已遗漏项目补充

### E.1 需要补充到计划书的模块

| 模块 | 当前状态 | 建议优先级 |
|---|---|---|
| IRR 计算 | 已实现，未在计划书中提及 | P2（PPT 生成可选） |
| 提示词模板 | 已实现，未在计划书中提及 | P1（核心依赖） |
| 数据归一化 | 已实现，未在计划书中详述 | P1（核心依赖） |
| 数据验证 | 已实现，未在计划书中详述 | P1（核心依赖） |

### E.2 环境配置遗漏

| 配置项 | 状态 | 影响 |
|---|---|---|
| LLM API Keys | 未在计划书中提及 | 无法调用 AI 解析 |
| Python 依赖 | 未在计划书中详述 | 运行时导入错误 |

### E.3 前端组件遗漏

| 组件 | 状态 | 说明 |
|---|---|---|
| `PptUpload.vue` | 已实现，未提及 | PDF 上传界面 |
| `PptParsing.vue` | 已实现，未提及 | 解析进度展示 |
| `PptGenerate.vue` | 已实现，未提及 | 风格选择和生成触发 |

### E.4 baodanppt 原始架构（重要参考）

baodanppt 项目是 TypeScript 实现，当前 Flask 融合需要理解其原始架构：

```
baodanppt/src/
├── api/
│   └── server.ts              # HTTP 服务器（路由、会话管理）
├── extraction/
│   ├── orchestrator.ts        # 提取编排器（Schema 验证、多类型支持）
│   ├── gemini-client.ts       # Gemini API 客户端
│   ├── pdf-preprocessor.ts    # PDF 预处理器（pymupdf 文本提取）
│   └── prompts.ts             # 各产品的 Prompt 模板
├── schemas/
│   ├── savings-plan.ts        # 储蓄险 Schema + 验证
│   ├── critical-illness.ts    # 重疾险 Schema
│   ├── iul.ts                 # IUL Schema
│   └── common.ts              # 共享 Schema（受保人、保单、年度利益行）
├── chat/
│   ├── chat-engine.ts         # 对话引擎（支持三种产品类型）
│   ├── interpretation-engine.ts # AI 解读引擎（计划书 JSON → 销售洞察）
│   └── outline-generator.ts   # PPT 大纲生成器
├── generation/
│   ├── pptx-generator.ts      # 主 PPT 生成器（20KB）
│   ├── composition-engine.ts   # 组合引擎（25KB）
│   ├── marp-renderer.ts       # Marp 渲染器（13KB）
│   └── image-gen.ts           # 图片生成
├── render/
│   ├── fast-pptx.ts           # 快速 PPTX 渲染（TypeScript）
│   ├── normalized-deck.ts     # 归一化 Deck 格式
│   └── index.ts               # 渲染入口
├── knowledge/                 # 公司知识库
├── planning/                  # Bundle 规划
├── bundles/                   # 多产品组合
└── pipeline/                  # 流水线编排
```

### E.5 渲染脚本对照表

| baodanppt 原始文件 | 当前 Flask 实现 | 状态 |
|---|---|---|
| `src/generation/pptx-generator.ts` | `api/insurance/ppt/renderer.py` | ⚠️ 需要适配 |
| `src/render/fast-pptx.ts` | 查找 `fast_pptx_renderer.py` | ❌ 文件不存在 |
| `src/generation/composition-engine.ts` | 未实现 | ❌ 缺失 |
| `scripts/slide_renderer.py` | 未调用 | ⚠️ 存在但未接入 |

### E.6 提示词模板详解

`api/insurance/ppt/prompts.py` 包含完整的提取提示词：

| 提示词 | 用途 | 关键特性 |
|---|---|---|
| `SAVINGS_PLAN_SYSTEM_PROMPT` | 储蓄险提取 | 130 行，包含场景判定规则、销售叙事 |
| `CI_PLAN_SYSTEM_PROMPT` | 重疾险提取 | 190 行，包含保障项目提取、家庭保护角色 |
| `IUL_SYSTEM_PROMPT` | IUL 提取 | 250 行，包含指数账户、杠杆倍数 |
| `build_savings_prompt()` | 构建储蓄险 prompt | 支持页面结构参考 |

**关键发现**：提示词已经非常完善，包含：
- 数据提取规则（表格扫描、数值处理）
- 场景判定规则（年龄 + 提领方案 → 教育金/养老金/财富传承）
- 销售叙事规则（不同场景的叙事模板）
- 输出格式要求（纯 JSON、至少 20 行、policy_year 从 1 开始）

---

## 附录 F：验证结果记录（2026-07-23）

### F.1 已验证正确的项目

| 项目 | 验证结果 | 说明 |
|---|---|---|
| 后端路由注册 | ✅ 正确 | `ppt_bp` 已注册到 `/insurance/ppt` |
| 数据库模型 | ✅ 正确 | `PptSession`、`PptCompany`、`PptProduct`、`PptTemplate`、`PptBundle` 已导入 |
| API 端点 | ✅ 正确 | 10 个端点与计划书一致 |
| 前端页面 | ✅ 正确 | Vue 原生四步流程已实现 |
| 前端 API 封装 | ✅ 正确 | `ppt-api.ts` 与后端路由匹配 |
| `migrate_014.py` 路径 | ✅ 正确 | 从 `api/insurance/db` 往上三层到达项目根目录 |

### F.2 已确认存在的问题

| 问题 | 严重度 | 状态 |
|---|---|---|
| 下载接口 `window.open()` 不带 Authorization header | 高 | 待修复 |
| 渲染脚本 `fast_pptx_renderer.py` 不存在 | 高 | 需确认使用 `slide_renderer.py` |
| 前后端字段命名不一致（`chat_history` vs `chatHistory`） | 中 | 待统一 |
| Bundle 只取第一个提取结果 | 中 | 待优化 |

### F.3 待验证项目

| 项目 | 验证方法 |
|---|---|
| `MIGRATION_ENABLED` 配置 | 检查环境变量或配置文件 |
| `ppt_work`、`uploads`、`downloads` 目录权限 | 尝试写入测试 |
| `PyMuPDF`、`python-pptx`、`httpx` 依赖 | `pip list` 检查 |
| LLM API key 配置 | 尝试调用解析接口 |

### F.4 测试文件状态

| 测试类型 | 状态 | 说明 |
|---|---|---|
| 单元测试 | ❌ 不存在 | 无 `tests/test_ppt*.py` 文件 |
| 集成测试 | ❌ 不存在 | 无端到端测试 |
| 提示词测试 | ❌ 不存在 | 无 prompts 效果验证 |

**建议**：在阶段一完成后，补充以下测试：
1. `test_extraction.py` - PDF 解析测试
2. `test_normalizer.py` - 数据归一化测试
3. `test_validator.py` - 数据验证测试
4. `test_renderer.py` - PPT 渲染测试
5. `test_routes.py` - API 端点测试