606 lines
23 KiB
Markdown
606 lines
23 KiB
Markdown
# 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 端点测试
|