baodan/docs/baodanppt融合同步计划书.md

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。

# 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 路径计算实际正确

# 当前代码
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

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

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

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

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

# 当前查找
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() 只取第一个成功提取结果

# 当前实现
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	✅

安装命令：

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 端点测试