baodan/docs/PPT与海报功能问题整改计划.md

PPT 与海报功能问题整改计划

文档版本：v1.0
编制日期：2026-07-27
适用范围：api/insurance/ppt/、api/insurance/poster/、PPT/海报管理后台、相关数据库迁移与部署配置
文档状态：待评审
目标：修复 PPT 和海报无法稳定生成的问题，打通保司、产品、模板、模型、文件和历史数据链路，并补齐安全与可运维能力

---

一、文档目的

当前 PPT 与海报模块已经具备页面、接口、数据库模型、迁移、LLM 调用和本地渲染代码，但各部分没有形成稳定闭环。用户表现为：

• PPT 上传或解析后无法生成；
• 海报没有可选产品或模板；
• 海报生成后无法预览、无法下载；
• 后台已经配置模型，但实际调用不生效；
• 保司、产品、模板和知识库数据之间没有完整关联；
• 不同部署环境、不同启动次数可能得到不同的数据状态。

本文档不是重新设计整个系统，而是基于现有代码做最小必要整改，按以下顺序处理：

1. 修复能够直接导致生成失败、数据泄露的 P0 问题；
2. 恢复 PPT、海报基础生成闭环；
3. 将耗时操作接入 BaoDan 现有 Celery、Redis 和数据库；
4. 打通公共保司、产品、模板和知识库数据；
5. 补齐安全、持久化、监控、测试和发布回滚能力。

---

二、审计边界与结论说明

2.1 已检查范围

范围	主要文件
PPT 前端	frontend/src/pages/PptPage.vue、frontend/src/pages/components/ppt/
海报前端	frontend/src/pages/PosterPage.vue、frontend/src/components/poster/
前端 API	frontend/src/utils/ppt-api.ts、poster-api.ts、api.ts
PPT 后端	api/insurance/ppt/
海报后端	api/insurance/poster/
配置管理	api/insurance/admin/ppt_admin_routes.py、ppt_admin_service.py
数据模型	api/insurance/models/ppt_*、poster_*、system_setting.py
数据迁移	api/insurance/db/migrate_014.py～migrate_018.py
部署	Dockerfile.dify-custom、docker-compose.dify.yml、deploy/sql/init.sql

2.2 已执行验证

检查项	结果
Python 代码编译检查	通过
Vue 前端生产构建	通过
当前源码环境 python-pptx	未安装
当前源码环境 PyMuPDF/fitz	未安装
静态保司配置	21 家
静态产品配置	7 个
静态 PPT 模板	7 个
海报模板种子数据	未发现
海报文案模板种子数据	未发现
PPT/海报自动化测试	未发现覆盖生成闭环的测试

2.3 结论口径

• 本文标记为“已确认”的问题，均可由当前代码结构直接证明。
• 外部模型账号余额、生产数据库实际内容、生产容器日志尚未在本次静态审计中验证。
• 实施前仍需采集一次生产数据库结构、迁移历史、配置完整度和失败日志，避免覆盖现有有效数据。

---

三、现状调用链

3.1 PPT 当前调用链

PptUpload
  → POST /insurance/ppt/upload
  → 保存 PDF + 创建 PptSession
  → POST /insurance/ppt/parse/{sessionId}
  → Web 进程后台线程解析 PDF
  → LLMClient 提取结构化数据
  → PptDataReview 人工核对
  → POST /insurance/ppt/generate/{sessionId}
  → normalizer + validator
  → PptRenderer
  → fast_pptx_renderer.py 子进程
  → 写入 downloads/{userId}/{sessionId}.pptx
  → 鉴权下载

主要断点：

• 源码环境缺依赖；
• 数据迁移顺序不稳定；
• slidesConfig 结构不一致；
• 前端风格与数据库模板不一致；
• 上传时选择的保司没有流转到生成阶段；
• 校验错误没有真正阻止生成；
• 后台线程不可恢复；
• 输出文件未持久化。

3.2 海报当前调用链

选择 reviewed 产品
  → 上传计划书 PDF
  → 上传请求内同步调用 LLM 解析
  → 人工确认客户数据
  → 选择海报模板、文案模板
  → 模板填充或 LLM 生成文案
  → 图片模型生成
  → 失败时 Pillow 降级
  → 写入 uploads/posters
  → 普通 URL 预览和下载

主要断点：

• 新环境没有 reviewed 产品、海报模板和文案模板；
• 海报文案设置没有进入调用链；
• 多图片供应商只做了页面配置，没有协议适配；
• 上传解析和图片生成是同步请求，超过前端 60 秒超时；
• 生成文件预览、下载不携带 JWT；
• 参考图没有从页面传到后端；
• 图片尺寸映射错误；
• 上传、结果文件未持久化。

---

四、问题总表

4.1 P0：必须先修

编号	问题	影响	主要根因
PPT-P0-01	slidesConfig 数据结构不一致	匹配到模板时渲染器可能直接 KeyError	迁移写对象，渲染器和前端要求数组
DB-P0-01	迁移顺序存在循环依赖	首次部署可能没有模板或字段	014 使用新版模型，017 才创建新版字段
DB-P0-02	迁移异常不回滚	一个字段冲突可导致后续迁移全部失败	PostgreSQL 事务进入 aborted 后仍继续
SEC-P0-01	任意登录用户可读取明文模型密钥	模型 API Key 泄露	settings GET 仅要求 JWT，数据库明文保存
SEC-P0-02	任意登录用户可查看、导出全体 PPT 历史	用户数据、文件路径泄露	管理历史接口仅要求 JWT
SEC-P0-03	海报文案可读取其他用户的 case 数据	跨用户客户信息泄露	caseUploadId 未校验所有权
DEP-P0-01	源码与 Docker 依赖不一致	本地解析、PPT 渲染直接失败	requirements 未声明全部生成依赖
POSTER-P0-01	海报预览和下载不携带 JWT	已生成图片仍显示失败	使用 <img src> 和 window.open
POSTER-P0-02	新环境没有完整海报基础数据	用户无法开始或无法进入下一步	无 reviewed 产品、海报/文案模板种子
POSTER-P0-03	海报文案模型配置不生效	后台配置正确但实际调用错误模型	复用了只读取 ppt_llm_* 的客户端
POSTER-P0-04	同步解析和生成超过请求超时	前端报失败，后台可能仍在执行	前端 60 秒，LLM 180 秒，Gunicorn 120 秒
DATA-P0-01	生成和上传文件未持久化	容器重建后历史文件全部失效	文件写在 /app/api/uploads、downloads

4.2 P1：基础可用后立即处理

编号	问题	影响
PPT-P1-01	前端风格与数据库模板风格不一致	多数模板配置永远查询不到
PPT-P1-02	上传时选择的保司在后续丢失	生成使用错误保司或要求重复选择
PPT-P1-03	公司知识库匹配没有进入生成主流程	公司介绍和证据数据为空
PPT-P1-04	多产品只用第一份数据决定模板和保司	跨险种、跨保司组合错误
PPT-P1-05	validator 错误只记录日志，不阻止生成	可输出错误保费、利益数据
POSTER-P1-01	poster_image_provider 未参与协议选择	豆包、智谱配置名义可选但实际不可用
POSTER-P1-02	图片响应只支持 b64_json	返回 URL 的供应商生成失败
POSTER-P1-03	管理员模板参考图未进入图片生成	模板参考图配置无效
POSTER-P1-04	用户填写参考图未传到下一步	页面输入无效
POSTER-P1-05	横版、方形尺寸会退回竖版	输出尺寸与用户选择不一致
POSTER-P1-06	图片 API 错误被无条件降级掩盖	配置错误被记录成“成功”
SEC-P1-01	上传仅检查扩展名或不检查	恶意文件、超大 PDF、资源耗尽
SEC-P1-02	自定义 Base URL 可访问任意地址	存在服务端请求内网风险
DATA-P1-01	JSON 与数据库形成双数据源	环境间保司、产品、模板数据漂移
DATA-P1-02	保留天数配置没有清理任务	客户数据、PDF、prompt 永久保留
API-P1-01	成功响应解包不统一	前端大量 data?.data ?? data，容易误判
TASK-P1-01	后台 daemon thread 不可恢复	Worker 重启后解析任务永久丢失
TASK-P1-02	生成缺少幂等控制	重复点击导致重复计费、并发覆盖文件
OBS-P1-01	health 只返回 ok	依赖、模型、模板、磁盘异常无法发现
TEST-P1-01	缺少端到端测试	每次改动都可能再次断链

4.3 P2：稳定性与体验优化

编号	问题	影响
DATA-P2-01	公司模型部分字段没有通过 to_dict 返回	shortEn 等品牌信息无法进入渲染器
DATA-P2-02	管理后台不能完整维护评级、亮点、知识目录	公共保司数据只能部分编辑
TASK-P2-01	LLM 限流只在单进程内生效	多 Worker 时无法控制总调用量
TASK-P2-02	配置保存后缓存最长 60 秒才生效	管理员误以为设置无效
UX-P2-01	降级图、AI 图无明显区分	用户无法判断实际生成方式
UX-P2-02	刷新页面后无法恢复生成步骤	长任务体验不稳定

---

五、重点问题根因与修复要求

5.1 PPT-P0-01：slidesConfig 结构错误

现状

• migrate_017.py 写入：

{
  "slides": [
    {"pageType": "cover"}
  ]
}

• PptTemplatesAdmin.vue、PptTemplate.to_dict() 和渲染器期望：

[
  {"pageType": "cover"}
]

• 渲染器 _slide_meta() 对对象使用整数下标，可能抛出 KeyError: 0。

修改方案

1. 将 migrate_017._build_default_slides_config() 返回值统一为数组。
2. 管理端、模型层、渲染器只接受数组，不再兼容多种永久格式。
3. 新增修复迁移，将历史对象结构转换为数组：

如果值是 {"slides": [...]} → 提取 slides
如果值已经是数组 → 原样保留
如果为空 → 根据 required_page_types_json 生成
如果无法解析 → 记录异常，不静默覆盖

4. 在 PptTemplate.to_dict() 中增加安全解析，非法 JSON 返回明确配置错误。
5. 渲染前验证 slidesConfig：
   • 必须为数组；
   • 每项必须有 pageType；
   • pageType 必须在允许集合内；
   • 至少包含一页。

涉及文件

• api/insurance/db/migrate_017.py
• 新增 api/insurance/db/migrate_019.py
• api/insurance/models/ppt_config.py
• api/insurance/ppt/scripts/fast_pptx_renderer.py
• api/insurance/admin/ppt_admin_service.py
• frontend/src/pages/admin/PptTemplatesAdmin.vue

验收

• 历史对象结构能够自动转为数组；
• 所有启用模板均能生成至少一页 PPT；
• 非法结构在管理后台明确显示“模板配置无效”；
• 不再出现 KeyError: 0。

---

5.2 DB-P0-01/P0-02：迁移顺序与事务

现状

1. deploy/sql/init.sql 的模板表缺少 slides_config_json。
2. migrate_014 使用包含该字段的新版 ORM 模型。
3. migrate_017 才添加字段。
4. migrate_015._add_column() 捕获错误后不回滚。
5. run_migrations() 捕获迁移异常后不统一回滚。
6. 每个 Web Worker 启动时都可能并发执行迁移。

修改原则

• 已经在生产执行过的迁移文件不作为唯一修复手段；
• 修正旧迁移以保证新环境可部署；
• 另加一个幂等修复迁移处理已有环境；
• 单个迁移必须原子提交；
• 失败必须回滚并停止，不允许“带病继续”；
• 迁移只能由一个进程执行。

修改方案

1. 更新 deploy/sql/init.sql，使新建表结构与当前模型一致。
2. 调整 migrate_014：
   • 使用 SQLAlchemy Inspector 检查表和字段；
   • 不在字段不存在时通过完整 ORM 模型查询；
   • 种子导入改为显式 SQL 或确保最新列已存在。
3. 修复 migrate_015：
   • 添加字段前先检查，不通过异常判断“已存在”；
   • 捕获异常时 rollback；
   • 任一必要字段失败时抛出异常。
4. 修复迁移调度器：
   • 每个迁移开始前 rollback 残留事务；
   • 迁移失败后 rollback；
   • 不记录失败迁移；
   • 必要迁移失败时停止应用启动。
5. PostgreSQL 使用 advisory lock，避免多个 Gunicorn Worker 同时迁移。
6. 新增 migrate_019.py：
   • 补齐缺失字段；
   • 修复 slides_config_json；
   • 校验 PPT、海报表；
   • 补必要索引；
   • 输出修复数量。
7. 提供只读迁移预检命令，显示：
   • 当前 schema；
   • 已执行迁移；
   • 缺失字段；
   • 异常配置数量。

涉及文件

• deploy/sql/init.sql
• api/insurance/db/__init__.py
• api/insurance/db/migrate_014.py
• api/insurance/db/migrate_015.py
• api/insurance/db/migrate_017.py
• api/insurance/db/migrate_018.py
• 新增 api/insurance/db/migrate_019.py
• scripts/setup/patch_app.py

验收

• 空数据库首次启动一次即可得到完整表、保司、产品和模板；
• 同一迁移重复执行三次结果一致；
• 两个进程并发启动时只有一个执行迁移；
• 故意制造字段冲突时能够 rollback，并阻止应用误报启动成功；
• SQLite 若继续声明支持，017/018 必须通过 SQLite 测试；否则文档明确只支持 PostgreSQL。

---

5.3 SEC-P0-01：模型密钥保护

现状

• GET /insurance/admin/ppt/settings 只要求登录；
• 返回所有 system_settings 原始值；
• API Key 以明文保存；
• 前端加载后会显示完整值，并在保存时再次回传。

修改方案

1. settings GET、available-models 和历史管理接口增加明确权限。
2. 设置项建立允许列表，禁止任意 key 写入。
3. 密钥类字段加密存储：
   • 复用项目已有密钥/加密能力；
   • 数据库只保存密文；
   • 日志不得输出明文。
4. GET 只返回：

{
  "poster_image_api_key_configured": true,
  "poster_image_api_key_masked": "sk-****abcd"
}

5. PUT 语义：
   • 字段缺失：保持不变；
   • 空字符串：不覆盖旧值；
   • 明确 clear=true：删除密钥；
   • 新密钥：加密后保存。
6. 增加密钥修改审计日志。
7. 对现有明文数据执行一次加密迁移。

涉及文件

• api/insurance/admin/ppt_admin_routes.py
• api/insurance/admin/ppt_admin_service.py
• api/insurance/models/system_setting.py
• frontend/src/pages/admin/PptSettingsAdmin.vue
• frontend/src/utils/ppt-admin-api.ts
• 新增密钥加解密工具或复用现有工具

验收

• 普通用户请求 settings 返回 403；
• 管理员看不到完整旧密钥；
• 数据库中不存在可直接使用的明文 API Key；
• 日志、错误响应和前端状态中不包含完整密钥。

---

5.4 SEC-P0-02/P0-03：历史权限与跨用户数据

修改方案

1. 管理历史列表、导出、删除统一要求 audit_view 或 config_manage。
2. 应用 get_data_scope()：
   • 超级管理员：全部；
   • 部门主管：本部门；
   • 普通用户：仅本人。
3. 海报 generate_copy() 必须校验：
   • case 存在；
   • case.user_id == current_user；
   • case 已确认；
   • case.product_id 与请求 productId 一致。
4. 海报 generate_poster() 同样校验 case、产品和模板。
5. 所有按 ID 查询的用户数据接口建立统一所有权检查。
6. 越权访问统一返回 404，避免暴露 ID 是否存在。

涉及文件

• api/insurance/admin/ppt_admin_routes.py
• api/insurance/admin/ppt_admin_service.py
• api/insurance/poster/service.py
• api/insurance/poster/routes.py
• api/insurance/middleware/auth_middleware.py

验收

• 用户 A 无法读取、生成或下载用户 B 的 case、文案和海报；
• 普通用户无法导出全体历史；
• 权限测试覆盖本人、同部门、跨部门和管理员四种身份。

---

5.5 DEP-P0-01：依赖统一

必须声明

依赖	用途
python-pptx	PPTX 生成
PyMuPDF	PDF 文本提取
PyPDF2/pypdf/pdfplumber	PDF 提取回退
Pillow	海报降级图
openai	OpenAI 兼容图片接口
httpx	LLM HTTP 调用

修改方案

1. 在 api/insurance/requirements.txt 声明全部直接依赖。
2. Dockerfile 安装该 requirements，不再维护另一份手写依赖列表。
3. 增加启动依赖自检。
4. 快速启动、完整部署文档使用同一安装命令。
5. 固定兼容版本区间，避免基础镜像升级导致 SDK 行为变化。

涉及文件

• api/insurance/requirements.txt
• Dockerfile.dify-custom
• docs/快速启动指南.md
• docs/部署文档_完整版.md

验收

• 新 Python 环境安装 requirements 后可导入全部生成依赖；
• Docker 构建阶段执行导入检查；
• 使用样例 DeckContract 能生成有效 PPTX；
• 无图片 API Key 时能生成明确标记的 fallback PNG。

---

5.6 POSTER-P0-01：鉴权预览和下载

修改方案

1. 海报 API 增加 Blob 下载方法，与 PPT 下载方式一致。
2. 前端通过 Axios 请求 Blob，创建临时 Object URL 供 <el-image> 预览。
3. 下载按钮复用同一 Blob，不再 window.open 受保护 URL。
4. 组件卸载或重新生成时释放 Object URL。
5. PPT 的 window.open 降级路径一并移除。
6. 历史页使用相同认证图片加载组件。

涉及文件

• frontend/src/utils/poster-api.ts
• frontend/src/components/poster/PosterStepPreview.vue
• frontend/src/pages/PosterHistoryPage.vue
• frontend/src/pages/components/ppt/PptResult.vue

验收

• 登录模式和访客模式均能预览、下载本人海报；
• 浏览器网络请求携带 Authorization；
• 用户之间不能互相下载；
• 多次预览不持续占用 Blob 内存。

---

5.7 POSTER-P0-02：基础数据初始化

修改方案

1. 至少准备：
   • 1 个 reviewed 测试产品；
   • 2 个海报模板；
   • 2 个文案模板。
2. 正式产品仍必须走“小册子解析 → 人工审核 → reviewed”。
3. 开发/验收种子与生产业务数据区分：
   • 开发环境自动导入；
   • 生产环境提供显式初始化命令；
   • 不自动覆盖管理员修改。
4. 页面空状态明确区分：
   • 没有产品；
   • 产品未审核；
   • 没有模板；
   • 没有文案模板。
5. 管理后台增加配置完整度提示。

涉及文件

• 新增 api/insurance/poster/config/ 或数据库种子文件
• 新增修复迁移/初始化脚本
• frontend/src/components/poster/PosterStepProduct.vue
• frontend/src/components/poster/PosterStepTemplate.vue
• 管理后台相关页面

验收

• 空数据库初始化后可以完整走通一条海报流程；
• 生产环境不会把未审核产品自动标为 reviewed；
• 缺配置时页面给出管理员可执行的处理提示。

---

5.8 POSTER-P0-03/P1-01：模型配置和供应商适配

目标

保留一套通用调用接口，但按用途读取不同配置：

ppt_extract   → ppt_llm_*
poster_copy   → poster_llm_*
poster_image  → poster_image_*

修改方案

1. LLMClient 支持传入用途或配置命名空间，不让海报文案继续读取 PPT 配置。
2. 不配置模型时不再返回 mock {}；正式接口应返回“模型未配置”错误。
3. 结构化输出执行真实 Schema/Pydantic 校验。
4. 图片供应商按协议拆分最小适配器：
   • OpenAI；
   • 豆包；
   • 智谱；
   • 自定义 OpenAI-compatible。
5. 同时支持：
   • b64_json；
   • 图片 URL 下载；
   • 各供应商允许的尺寸；
   • 参考图是否受支持。
6. 保存配置前提供测试连接。
7. 图片生成记录增加：
   • provider；
   • model；
   • generation_mode；
   • error_code；
   • latency；
   • fallback_reason。
8. AI 失败时是否允许 fallback 由明确配置决定。

涉及文件

• api/insurance/ppt/llm_client.py
• api/insurance/poster/copy_generator.py
• api/insurance/poster/manual_parser.py
• api/insurance/poster/image_generator.py
• api/insurance/poster/service.py
• api/insurance/models/poster_record.py
• frontend/src/pages/admin/PptSettingsAdmin.vue

验收

• 海报文案实际使用后台配置的 poster_llm_*；
• 每个声明支持的图片供应商至少有一个契约测试；
• 错误 Key、错误模型、欠费、超时返回不同错误码；
• 空对象或缺少标题、正文、行动号召时不能进入下一步。

---

5.9 POSTER-P0-04/TASK-P1-01：异步任务

目标状态机

created
  → queued
  → parsing / generating
  → review_required / done
  → failed

修改方案

1. 复用 BaoDan Celery，不新增独立任务系统。
2. 上传接口只完成：
   • 文件校验；
   • 保存；
   • 创建记录；
   • 投递任务；
   • 返回任务 ID。
3. Celery 负责：
   • PDF 解析；
   • 产品小册子解析；
   • 海报图片生成；
   • 必要时 PPT 渲染。
4. Redis 只用于任务锁和进度，不作为最终状态唯一来源。
5. 数据库保存最终状态、错误和结果路径。
6. 增加幂等键：
   • 同一 session 同一版本只生成一次；
   • 重复点击返回现有任务；
   • 明确“重新生成”时创建新版本。
7. Redis 锁使用随机 owner token，释放时比较 owner。
8. 前端按 2 秒轮询，连续错误采用退避。
9. 页面刷新后根据 session/record ID 恢复进度。
10. Celery 重试仅覆盖网络、限流等可重试错误；数据错误不重试。

接口调整

接口	调整
POST /poster/case-upload	立即返回 case ID 和 queued
GET /poster/case-upload/{id}	返回解析进度、状态、错误
POST /poster/generate	返回 generation record/task ID
GET /poster/records/{id}	返回生成进度、模式、文件状态
POST /ppt/generate/{sessionId}	建议返回任务状态，保留兼容期

验收

• 创建任务接口 3 秒内返回；
• 5 分钟解析任务不会导致浏览器请求超时；
• Worker 重启后任务可重试或明确失败；
• 重复点击不会重复扣费；
• 用户可以刷新页面并恢复进度。

---

5.10 DATA-P0-01：文件持久化

统一目录

/app/api/storage/insurance/
├── uploads/
│   ├── ppt/
│   ├── poster-cases/
│   └── manuals/
├── outputs/
│   ├── ppt/
│   └── posters/
└── work/

修改方案

1. 新增 INSURANCE_STORAGE_ROOT 配置，默认指向 BaoDan 持久化 storage。
2. 数据库保存相对对象键，不保存依赖当前工作目录的绝对路径。
3. 下载时通过统一 StorageService 解析路径。
4. 使用 os.path.commonpath 校验安全目录，不使用字符串 startswith。
5. Docker API、Worker 共享同一 storage volume。
6. 工作目录可清理，结果目录按保留策略清理。
7. 对旧路径提供一次迁移/兼容读取。

涉及文件

• api/insurance/config.py
• api/insurance/ppt/routes.py
• api/insurance/ppt/renderer.py
• api/insurance/poster/service.py
• api/insurance/poster/routes.py
• docker-compose.dify.yml
• Worker volume 配置

验收

• API 容器重建后历史文件仍能下载；
• Worker 生成的文件 API 能读取；
• 非 storage 路径无法通过下载接口访问；
• 清理任务不会误删仍在保留期的文件。

---

5.11 PPT-P1-01～P1-04：模板、保司、产品和知识库

统一运行时数据源

运行时以数据库为唯一权威数据源；JSON 仅作为版本化种子，不在请求中直接读取。

生成上下文

{
  "customer": {},
  "plans": [
    {
      "planType": "savings",
      "company": {},
      "product": {},
      "extractedData": {},
      "evidence": []
    }
  ],
  "template": {},
  "generation": {}
}

修改方案

1. 上传时的 companyId 保留到每个 extraction。
2. 解析后用产品名称、别名匹配产品和保司。
3. 匹配优先级：
   • 用户强制选择；
   • 产品目录精确匹配；
   • 产品别名；
   • 保司别名；
   • 无法确定时人工确认。
4. 低置信度匹配不得自动进入正式生成。
5. 将 company-kb/match 接入解析完成流程。
6. 调用 BaoDan 知识库获取公司介绍证据，结果保存：
   • 文档 ID；
   • 文件名；
   • 片段；
   • 版本/更新时间。
7. 多产品按每份 plan 保存独立保司，不再使用一个全局 companyId。
8. 前端不硬编码风格列表，按险种和产品读取可用模板。
9. 模板选择校验：
   • status；
   • planType；
   • applicableCompanyIds；
   • applicableProductIds。
10. 公司 to_dict() 补齐品牌字段，管理后台允许维护知识目录、评级和亮点。
11. 增加显式种子 upsert 命令，默认只新增，不覆盖人工修改。

涉及文件

• api/insurance/ppt/routes.py
• api/insurance/ppt/parse_worker.py 或对应 Celery task
• api/insurance/ppt/knowledge.py
• api/insurance/ppt/renderer.py
• api/insurance/models/ppt_config.py
• api/insurance/admin/ppt_admin_service.py
• frontend/src/pages/components/ppt/PptUpload.vue
• frontend/src/pages/components/ppt/PptDataReview.vue
• frontend/src/pages/components/ppt/PptGenerate.vue

验收

• 同一产品在 PPT 和海报中使用相同保司名称、Logo 和卖点；
• 上传阶段选择的保司自动带入生成阶段；
• 两家保司的组合方案分别显示各自公司信息；
• 公司介绍可以追溯到知识库证据；
• 前端只展示当前方案真正可用的模板。

---

5.12 PPT-P1-05：正式数据校验

修改方案

1. 统一校验级别：
   • error：禁止生成；
   • warn：用户确认后允许；
   • info：展示但不阻塞。
2. 生成接口必须再次服务端校验，不能依赖前端。
3. 用户确认 warning 时保存：
   • 确认人；
   • 时间；
   • 校验快照；
   • 数据版本。
4. PPT 历史记录保存正式输入快照和校验摘要。
5. 关键保险数字禁止由 LLM 补造。

验收

• 构造缺少保费、缴费年期或利益表的数据时生成返回 4xx；
• warning 未确认不能生成；
• 已生成文件可追溯到输入数据和校验版本。

---

5.13 SEC-P1-01/P1-02：上传与外部请求安全

文件上传规则

项目	建议规则
文件类型	仅 PDF
文件头	必须为合法 PDF
单文件大小	配置化，默认不超过 30MB
页数	配置化，默认不超过 200 页
单会话文件数	默认不超过 3
加密 PDF	明确拒绝并提示
文件名	不使用原始文件名作为物理路径
解析超时	任务级限制

自定义 Base URL 规则

• 默认只允许 HTTPS；
• 拒绝 localhost、环回、私网、链路本地和云元数据地址；
• DNS 解析后校验最终 IP；
• 禁止跟随到内网的重定向；
• 可配置供应商域名白名单；
• 连接测试设置短超时和响应大小限制。

验收

• 伪造扩展名、超大文件、加密 PDF、超页数 PDF 被拒绝；
• 127.0.0.1、169.254.169.254、私网地址不能作为自定义 Base URL；
• 文件拒绝不创建脏记录。

---

5.14 DATA-P1-02：隐私、保留和清理

敏感数据

• 上传的计划书 PDF；
• 客户姓名、年龄、性别；
• 保额、保费、利益演示；
• 解析结果和人工确认数据；
• AI 原始文案；
• 生成 prompt；
• 模型调用日志。

修改方案

1. 明确保留策略的适用对象，而不只配置历史记录天数。
2. 增加每日 Celery 清理任务。
3. 删除顺序：
   • 标记待删除；
   • 删除物理文件；
   • 清理或匿名化数据库数据；
   • 写审计记录。
4. prompt 日志默认不保存完整客户数据，保存脱敏摘要或 hash。
5. 发送外部模型前记录供应商、用途和数据范围。
6. 管理后台提供按用户/会话删除能力。
7. 明确失败任务和临时工作目录的短保留期。

验收

• 将保留期设置为测试值后，过期文件和记录能自动清理；
• 清理任务可重复执行；
• 日志中搜索不到完整保额、保费和 API Key；
• 删除后历史接口不再返回失效下载链接。

---

5.15 API-P1-01：接口响应统一

统一格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

修改方案

1. PPT、海报路由统一使用 success()、error()。
2. Service 返回业务数据或抛出业务异常，不返回第二层完整响应包装。
3. 前端 Axios 拦截器只解包一次。
4. 删除：

res?.data?.data ?? res?.data

5. 为任务类接口统一字段：
   • taskId
   • status
   • progress
   • message
   • errorCode
   • retryable
6. 在 API 文档补齐请求、响应和错误码。

验收

• 所有 PPT/海报成功响应只有一层 data；
• 4xx/5xx 错误码与页面提示一致；
• TypeScript 为接口响应提供明确类型，不再使用主要流程 any。

---

六、文件级修改清单

文件/目录	修改内容	优先级
api/insurance/db/__init__.py	迁移锁、失败回滚、失败停止、原子记录	P0
api/insurance/db/migrate_014.py	修复模板种子导入顺序	P0
api/insurance/db/migrate_015.py	Inspector 检查字段，移除异常驱动流程	P0
api/insurance/db/migrate_017.py	slidesConfig 改为数组	P0
api/insurance/db/migrate_018.py	数据库方言兼容	P1
api/insurance/db/migrate_019.py	修复已有 schema 和模板数据	P0
deploy/sql/init.sql	同步最新表结构	P0
api/insurance/requirements.txt	补齐 PPT、PDF、海报依赖	P0
Dockerfile.dify-custom	安装统一 requirements 并自检	P0
api/insurance/ppt/routes.py	模板校验、正式数据校验、异步生成、持久化路径	P0/P1
api/insurance/ppt/parse_worker.py	迁移到 Celery，保留兼容入口后删除线程	P1
api/insurance/ppt/renderer.py	配置预检、输出校验、持久化路径	P0
api/insurance/ppt/scripts/fast_pptx_renderer.py	严格验证 slidesConfig，失败不误报成功	P0
api/insurance/ppt/llm_client.py	配置命名空间、真实 Schema 校验、禁用 mock 成功	P0
api/insurance/ppt/knowledge.py	接入真实知识库证据	P1
api/insurance/poster/service.py	所有权、状态校验、异步任务、统一响应	P0
api/insurance/poster/image_generator.py	供应商适配、尺寸、响应格式、fallback 标记	P0/P1
api/insurance/poster/copy_generator.py	使用 poster LLM 配置并校验输出	P0
api/insurance/poster/routes.py	统一响应、鉴权下载、安全路径	P0
api/insurance/admin/ppt_admin_routes.py	设置、历史权限收紧	P0
api/insurance/admin/ppt_admin_service.py	密钥掩码、允许列表、配置验证	P0
api/insurance/models/system_setting.py	密钥字段处理或关联加密服务	P0
api/insurance/models/poster_record.py	任务、供应商、模式、错误字段	P1
api/insurance/models/ppt_config.py	完整公司字段、安全 JSON 解析	P1
frontend/src/utils/api.ts	任务请求策略、统一响应	P1
frontend/src/utils/poster-api.ts	鉴权 Blob、状态接口类型	P0
frontend/src/components/poster/*	恢复任务、参考图、错误和 fallback 状态	P0/P1
frontend/src/pages/components/ppt/*	动态模板、保司流转、任务恢复	P1
frontend/src/pages/admin/PptSettingsAdmin.vue	密钥掩码、连接测试、配置完整度	P0
docker-compose.dify.yml	API/Worker 共享持久化 storage	P0

---

七、分阶段实施计划

Phase 0：生产现状快照与回归基线

预计工作量：0.5 人日

任务

• 备份数据库；
• 导出 db_migration_history；
• 导出相关表字段；
• 统计保司、产品、PPT 模板、海报模板、文案模板数量；
• 检查 slides_config_json 的实际结构；
• 收集最近 PPT、海报失败日志；
• 准备脱敏 PDF 样例和预期结果。

产出

• 生产数据快照；
• 迁移前检查报告；
• 可重复的失败样例；
• 回归测试基线。

完成标准

• 能明确当前失败发生在上传、解析、模板选择、渲染还是下载阶段；
• 所有修复均可用同一组样例复测。

---

Phase 1：紧急 P0 修复

预计工作量：2 人日

任务

• 修复 slidesConfig 结构；
• 修复迁移顺序、事务回滚和迁移锁；
• 增加修复迁移 019；
• 收紧 settings、历史权限；
• 修复海报 case 所有权；
• 补齐依赖；
• 修复海报鉴权预览和下载；
• 将文件根目录改到持久化 storage。

完成标准

• 不配置外部图片模型时，fallback 海报可生成、预览和下载；
• 储蓄险样例能够生成可打开的 PPTX；
• 普通用户不能读取模型密钥和全体历史；
• 容器重启后已生成文件仍存在。

---

Phase 2：模型和海报基础闭环

预计工作量：2 人日

任务

• 海报文案读取 poster_llm_*；
• 图片供应商按协议适配；
• 真实结构化输出校验；
• 初始化海报模板和文案模板；
• 修复参考图、尺寸；
• 区分 AI 成功、fallback 成功和失败；
• 增加模型连接测试。

完成标准

• 模板文案和 AI 文案均可用；
• 至少一个正式图片供应商通过真实测试；
• 错误模型配置不会被误报为成功；
• 生成记录包含真实 provider、model 和 generation_mode。

---

Phase 3：异步任务和幂等

预计工作量：2 人日

任务

• 将海报 case 解析接入 Celery；
• 将海报图片生成接入 Celery；
• 将 PPT 解析从后台线程迁移到 Celery；
• 评估 PPT 渲染是否同步保留或异步化；
• 增加状态、进度、错误和重试字段；
• 增加幂等键；
• 前端支持轮询和刷新恢复。

完成标准

• 任务创建请求 3 秒内返回；
• Worker 重启后状态可解释；
• 重复点击不重复生成、计费；
• 任务失败可区分可重试和不可重试。

---

Phase 4：公共保司、产品、模板与知识库

预计工作量：2 人日

任务

• 建立统一 GenerationContext；
• 上传保司信息贯穿解析、审核和生成；
• 自动匹配产品和保司；
• 低置信度人工确认；
• 接入 BaoDan 知识库证据；
• 多产品独立携带公司；
• 前端动态读取可用模板；
• 统一 JSON 种子和数据库策略。

完成标准

• PPT、海报共享同一保司、产品数据；
• 跨保司方案公司信息不串用；
• 公司介绍有证据来源；
• 模板适用范围生效。

---

Phase 5：安全、隐私与运维

预计工作量：1.5 人日

任务

• 文件上传限制；
• 自定义 Base URL 安全校验；
• API Key 加密和掩码；
• 数据保留和清理任务；
• prompt 和日志脱敏；
• 增强 readiness；
• 结构化日志和关键指标。

完成标准

• 安全测试通过；
• 过期文件可自动清理；
• health 能识别依赖、配置和存储异常；
• 日志不包含完整密钥和客户敏感数字。

---

Phase 6：自动化测试、灰度和上线

预计工作量：2 人日

任务

• 单元测试；
• API 集成测试；
• Celery 任务测试；
• 前端端到端测试；
• 数据迁移演练；
• 容器重建测试；
• 灰度开关；
• 上线和回滚演练；
• 更新 API、部署、测试和变更日志文档。

完成标准

• P0/P1 验收用例全部通过；
• 旧数据修复结果有统计；
• 灰度期间无跨用户访问、密钥泄露和文件丢失；
• 回滚方案演练成功。

---

八、测试计划

8.1 单元测试

编号	测试内容
UT-PPT-01	对象形式 slidesConfig 转换为数组
UT-PPT-02	非法 slidesConfig 被拒绝
UT-PPT-03	风格、险种、保司、产品模板匹配
UT-PPT-04	validator error 阻止生成
UT-PPT-05	多产品分别携带公司
UT-POSTER-01	文案模板变量替换
UT-POSTER-02	海报文案缺字段被拒绝
UT-POSTER-03	各图片供应商响应解析
UT-POSTER-04	横版、方形、竖版尺寸映射
UT-SEC-01	安全文件路径判断
UT-SEC-02	Base URL 私网拦截
UT-DB-01	迁移重复执行幂等

8.2 API 集成测试

编号	场景	预期
API-PPT-01	上传合法 PDF	返回 sessionId
API-PPT-02	上传伪 PDF	4xx
API-PPT-03	解析任务提交	3 秒内返回 queued
API-PPT-04	无效数据生成	4xx，包含校验问题
API-PPT-05	合法数据生成	返回任务，最终 done
API-PPT-06	用户 B 下载用户 A 文件	404
API-POSTER-01	无 reviewed 产品	返回明确配置状态
API-POSTER-02	访问他人 caseUploadId	404
API-POSTER-03	模型未配置	明确错误，不返回空文案
API-POSTER-04	图片 API 失败且允许 fallback	fallback_success
API-POSTER-05	图片 API 失败且禁止 fallback	failed
API-SEC-01	普通用户读取 settings	403
API-SEC-02	普通用户导出全体历史	403

8.3 端到端测试

1. 储蓄险 PDF → 解析 → 人工核对 → PPT → 下载；
2. 重疾险 PDF → business 模板 → PPT → 下载；
3. IUL PDF → 数据校验 → PPT → 下载；
4. Reviewed 产品 → 客户计划书 → 模板文案 → 海报 → 预览 → 下载；
5. Reviewed 产品 → AI 文案 → AI 海报；
6. 图片供应商失败 → fallback 海报；
7. 两家保司组合 → 自动匹配 → 对比 PPT；
8. 页面刷新 → 恢复任务；
9. API/Worker 容器重建 → 历史文件仍可下载；
10. 普通用户越权访问 → 全部拒绝。

8.4 数据库迁移测试

至少准备四种数据库状态：

1. 完全空库；
2. 只执行到 014；
3. 015～018 部分字段存在；
4. slides_config_json 同时包含对象、数组、空值和非法 JSON。

每种状态验证：

• 迁移一次成功；
• 再执行两次无副作用；
• 迁移失败可回滚；
• 数据数量和模板配置符合预期。

---

九、监控与健康检查

9.1 健康检查分层

检查	内容
/health/live	进程存活
/health/ready	DB、Redis、storage 可写、必要表字段
/ppt/health	PPT 依赖、模板数量、渲染器可执行
/poster/health	reviewed 产品、模板、文案模板、图片模型配置

9.2 关键指标

• PPT 上传成功率；
• PDF 解析成功率和平均耗时；
• PPT 渲染成功率和页数；
• 海报 AI 成功率；
• 海报 fallback 比例；
• 模型超时、限流、鉴权错误；
• 任务排队长度；
• 存储剩余空间；
• 历史文件缺失数量；
• 模板配置错误数量。

9.3 日志字段

requestId
taskId
sessionId / recordId
userId（必要时脱敏）
provider
model
status
durationMs
errorCode
retryable
fallbackReason

---

十、发布与回滚

10.1 上线前

• 数据库备份；
• storage 目录备份；
• 导出迁移历史；
• 运行迁移预检；
• 在生产副本演练迁移 019；
• 验证旧 PPT、海报历史读取；
• 准备功能开关：
  • PPT_GENERATION_ENABLED
  • POSTER_GENERATION_ENABLED
  • POSTER_AI_IMAGE_ENABLED
  • POSTER_FALLBACK_ENABLED

10.2 灰度顺序

1. 只开放管理员和测试账号；
2. 开放 PPT 基础生成；
3. 开放海报模板/fallback 模式；
4. 开放 AI 文案；
5. 开放 AI 图片；
6. 开放全部用户。

10.3 回滚原则

• 代码回滚不自动回滚已成功的数据修复；
• 新字段保持向后兼容；
• migration 019 不删除旧字段和旧文件；
• 功能异常优先关闭开关，不立即执行破坏性数据库回滚；
• 文件路径迁移期间保留旧路径兼容读取；
• 回滚后仍需保证历史文件可下载。

10.4 回滚触发条件

• PPT/海报生成失败率持续超过基线；
• 出现跨用户数据访问；
• 模型密钥暴露；
• 迁移导致表结构异常；
• 生成任务大量重复计费；
• storage 文件无法读取；
• 数据校验失效并输出错误保险数字。

---

十一、文档同步清单

实施代码时必须同步更新：

文档	更新内容
保险智能客服系统_API接口文档.md	异步任务、状态、错误码、鉴权
保险智能客服系统_需求文档.md	PPT/海报业务规则和异常场景
保险智能客服系统_测试用例.md	本文测试用例
部署文档_完整版.md	依赖、storage、Celery、配置
快速启动指南.md	统一依赖安装和验证
PPT与海报功能开发任务清单.md	修复任务状态
CHANGELOG.md	安全、迁移、生成链路修复

---

十二、实施约束

1. 自研代码仍全部位于 api/insurance/。
2. 不修改 BaoDan 核心模块来承载业务逻辑。
3. 复用 BaoDan 数据库、Redis、Celery、日志和认证。
4. 不在一次提交中同时重构无关模块。
5. 每项代码修改必须关联本文问题编号。
6. 先写失败测试，再修复对应问题。
7. 不以 fallback 掩盖配置错误。
8. 不以“前端已经校验”为理由跳过服务端校验。
9. 不提交 .env、API Key、客户 PDF 或未脱敏样例。
10. 迁移必须在生产数据副本上演练后上线。

---

十三、完成定义

只有同时满足以下条件，PPT 与海报模块才可标记为完成：

• 空数据库首次部署一次成功；
• 迁移重复执行幂等；
• PPT 三个险种样例均可生成和下载；
• 海报模板、AI、fallback 三种路径状态明确；
• 生成文件在容器重建后仍存在；
• PPT、海报使用同一公共保司和产品数据；
• 模板配置实际进入渲染器；
• 普通用户无法读取密钥、全体历史和他人 case；
• 所有耗时任务可恢复、可追踪、可幂等；
• 关键数据错误会阻止正式生成；
• health 能发现依赖、配置、数据库和存储问题；
• P0/P1 自动化测试全部通过；
• 发布和回滚演练完成；
• API、部署、测试、变更日志文档同步完成。

---

十四、预计工作量

阶段	预计人日
Phase 0：现状快照	0.5
Phase 1：紧急 P0	2
Phase 2：模型和海报闭环	2
Phase 3：异步任务	2
Phase 4：公共数据打通	2
Phase 5：安全与运维	1.5
Phase 6：测试与上线	2
合计	约 12 人日

说明：

• 以上为单人连续开发的技术工作量估算；
• 不包含外部模型账号申请、知识库资料整理、业务方核对产品规则的等待时间；
• Phase 1 完成后可恢复基础可用；
• Phase 4 完成后，公共保司、产品、模板和知识库才算真正连通；
• Phase 6 完成后才建议面向全部生产用户开放。