baodan/docs/PPT与海报功能开发任务清单.md

# PPT 与海报功能 — 开发任务清单

> 来源：[PPT与海报功能完整解决方案.md](PPT与海报功能完整解决方案.md)
> 完成一项勾一项。格式：`- [ ]` → `- [x]`
> 核心约束：不修改当前可正常运行的功能，所有改动纯增量。

---

## Phase P1：数据库 + 模型层（约 1 天）

### P1.1 迁移脚本 migrate_015 — 扩展现有表

- [x] **P1.1.1** 扩展 `insurance_ppt_companies` — 新增 3 字段
  - [x] ALTER TABLE ADD COLUMN `logo_url VARCHAR(500)`
  - [x] ALTER TABLE ADD COLUMN `status SMALLINT DEFAULT 1`
  - [x] ALTER TABLE ADD COLUMN `sort_order INTEGER DEFAULT 0`
  - [x] UPDATE 现有数据 `status = 1`（默认启用）
  - [ ] 验证：现有 PPT 生成流程不受影响

- [x] **P1.1.2** 扩展 `insurance_ppt_products` — 新增 16 字段
  - [x] ALTER TABLE ADD COLUMN `product_code VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `product_type VARCHAR(20)`
  - [x] ALTER TABLE ADD COLUMN `coverage_period VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `payment_period VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `insured_age_range VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `waiting_period VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `highlights TEXT`
  - [x] ALTER TABLE ADD COLUMN `extra_fields TEXT`
  - [x] ALTER TABLE ADD COLUMN `status SMALLINT DEFAULT 1`
  - [x] ALTER TABLE ADD COLUMN `sort_order INTEGER DEFAULT 0`
  - [x] ALTER TABLE ADD COLUMN `updated_at TIMESTAMP`
  - [x] ALTER TABLE ADD COLUMN `manual_file_url VARCHAR(500)`
  - [x] ALTER TABLE ADD COLUMN `manual_parse_status VARCHAR(20) DEFAULT 'none'`
  - [x] ALTER TABLE ADD COLUMN `manual_parsed_rules TEXT`
  - [x] ALTER TABLE ADD COLUMN `manual_reviewed_by VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `manual_reviewed_at TIMESTAMP`
  - [ ] 验证：现有 PPT 产品列表接口不受影响

- [x] **P1.1.3** 扩展 `insurance_ppt_templates` — 新增 6 字段
  - [x] ALTER TABLE ADD COLUMN `name VARCHAR(100)`
  - [x] ALTER TABLE ADD COLUMN `scenario_tag VARCHAR(50)`
  - [x] ALTER TABLE ADD COLUMN `preview_image VARCHAR(500)`
  - [x] ALTER TABLE ADD COLUMN `applicable_company_ids TEXT`
  - [x] ALTER TABLE ADD COLUMN `applicable_product_ids TEXT`
  - [x] ALTER TABLE ADD COLUMN `status SMALLINT DEFAULT 1`
  - [ ] 验证：现有 PPT 模板列表接口不受影响

### P1.2 迁移脚本 migrate_015 — 创建新表

- [x] **P1.2.1** 创建 `insurance_ppt_history` 表 + 索引
- [x] **P1.2.2** 创建 `poster_case_uploads` 表
- [x] **P1.2.3** 创建 `poster_templates` 表（AI 生图方案，含 style_description/color_scheme/reference_image）
- [x] **P1.2.4** 创建 `poster_copy_templates` 表
- [x] **P1.2.5** 创建 `poster_records` 表 + 索引
- [x] **P1.2.6** 创建 `system_settings` 表
- [x] **P1.2.7** 插入种子数据（ppt_history_retention_days / poster_history_retention_days 默认 365 天）

### P1.3 SQLAlchemy 模型

- [x] **P1.3.1** 更新 `models/ppt_config.py` — PptCompany 模型新增 logo_url/status/sort_order 字段 + to_dict 更新
- [x] **P1.3.2** 更新 `models/ppt_config.py` — PptProduct 模型新增 16 字段 + to_dict 更新
- [x] **P1.3.3** 更新 `models/ppt_config.py` — PptTemplate 模型新增 6 字段 + to_dict 更新
- [x] **P1.3.4** 新建 `models/ppt_history.py` — PptHistory 模型
- [x] **P1.3.5** 新建 `models/poster_case_upload.py` — PosterCaseUpload 模型
- [x] **P1.3.6** 新建 `models/poster_template_model.py` — PosterTemplate 模型（海报模板）
- [x] **P1.3.7** 新建 `models/poster_copy_template.py` — PosterCopyTemplate 模型
- [x] **P1.3.8** 新建 `models/poster_record.py` — PosterRecord 模型
- [x] **P1.3.9** 新建 `models/system_setting.py` — SystemSetting 模型
- [x] **P1.3.10** 更新 `models/__init__.py` — 注册所有新模型

- [x] **P1.3.11** 验证：`python -c "from insurance.models import *"` 无报错

### P1.4 路由注册

- [x] **P1.4.1** 更新 `api/insurance/routes.py` — 追加 `ppt_admin_bp` Blueprint 注册
- [x] **P1.4.2** 更新 `api/insurance/routes.py` — 追加 `poster_bp` Blueprint 注册
- [ ] **P1.4.3** 验证：`curl http://localhost:5001/insurance/admin/ppt/health` 返回 200
- [ ] **P1.4.4** 验证：现有 `/insurance/ppt/render-options` 接口不受影响

---

## Phase P2：管理后台 — 后端 API（约 2 天）

### P2.1 管理后台服务层

- [x] **P2.1.1** 新建 `admin/ppt_admin_service.py` — PptAdminService 类
- [x] **P2.1.2** 保司 CRUD — list_companies（分页 + status 筛选 + keyword 搜索）
- [x] **P2.1.3** 保司 CRUD — create_company
- [x] **P2.1.4** 保司 CRUD — update_company
- [x] **P2.1.5** 保司 CRUD — update_company_status（启用/停用）
- [x] **P2.1.6** 产品 CRUD — list_products（分页 + company_id/plan_type/status 筛选）
- [x] **P2.1.7** 产品 CRUD — create_product
- [x] **P2.1.8** 产品 CRUD — update_product
- [x] **P2.1.9** 产品 CRUD — update_product_status
- [x] **P2.1.10** 产品小册子 — upload_manual（上传 PDF 文件）
- [x] **P2.1.11** 产品小册子 — parse_manual（调用 LLM 解析 PDF → 更新 manual_parsed_rules + status=parsed）
- [x] **P2.1.12** 产品小册子 — review_manual（管理员核对 → status=reviewed）
- [x] **P2.1.13** PPT 模板 CRUD — list/create/update/update_status
- [x] **P2.1.14** 海报模板 CRUD — list/create/update/update_status（含参考图上传）
- [x] **P2.1.15** 文案模板 CRUD — list/create/update/delete
- [x] **P2.1.16** 历史记录 — list_history（管理员查看全部 PPT+海报历史）
- [x] **P2.1.17** 历史记录 — export_history_csv
- [x] **P2.1.18** 历史记录 — delete_history（软删除）
- [x] **P2.1.19** 系统配置 — get_settings / update_settings

### P2.2 管理后台路由层

- [x] **P2.2.1** 新建 `admin/ppt_admin_routes.py` — ppt_admin_bp Blueprint
- [x] **P2.2.2** 保司管理路由 — GET/POST /companies, PUT /companies/{id}, PUT /companies/{id}/status
- [x] **P2.2.3** 产品管理路由 — GET/POST /products, PUT /products/{id}, PUT /products/{id}/status
- [x] **P2.2.4** 产品小册子路由 — POST /products/{id}/manual/upload, POST /products/{id}/manual/parse, PUT /products/{id}/manual/review
- [x] **P2.2.5** PPT 模板路由 — GET/POST /templates, PUT /templates/{id}, PUT /templates/{id}/status
- [x] **P2.2.6** 海报模板路由 — GET/POST /poster-templates, PUT /poster-templates/{id}, PUT /poster-templates/{id}/status
- [x] **P2.2.7** 文案模板路由 — GET/POST /copy-templates, PUT /copy-templates/{id}, DELETE /copy-templates/{id}
- [x] **P2.2.8** 历史记录路由 — GET /history, GET /history/export, DELETE /history/{id}
- [x] **P2.2.9** 系统配置路由 — GET /settings, PUT /settings
- [x] **P2.2.10** 验证：所有管理接口需 `permission_required("config_manage")`，无权限返回 1004

---

## Phase P3：管理后台 — 前端页面（约 2 天）

### P3.1 API 封装 + 路由注册

- [x] **P3.1.1** 新建 `utils/ppt-admin-api.ts` — PPT 管理后台 API 封装
- [x] **P3.1.2** 更新 `router/index.ts` — 注册 7 个管理端路由（需 config_manage 权限）
- [x] **P3.1.3** 更新 `App.vue` 侧边栏 — 新增"PPT/海报配置"折叠子菜单（7 个入口）

### P3.2 管理页面

- [x] **P3.2.1** 新建 `admin/PptCompaniesAdmin.vue` — 保司管理
  - [x] 表格：公司名/简称/编码/Logo/状态/排序
  - [x] 筛选：状态下拉 + 名称搜索
  - [x] 弹窗：新增/编辑表单（含 Logo 上传）
  - [x] 操作：启用/停用按钮
- [x] **P3.2.2** 新建 `admin/PptProductsAdmin.vue` — 产品管理
  - [x] 表格：产品名/所属保司/类型/状态/小册子状态
  - [x] 筛选：保司下拉 + 类型下拉 + 状态下拉
  - [x] 弹窗：新增/编辑表单（基本信息 + 扩展字段）
  - [x] 操作：启用/停用 + 上传小册子 + 解析 + 核对
- [x] **P3.2.3** 新建 `admin/PptTemplatesAdmin.vue` — PPT 模板管理
  - [x] 表格：名称/类型/风格/场景标签/状态
  - [x] 弹窗：编辑表单（名称、场景标签、预览图上传、适用范围多选）
- [x] **P3.2.4** 新建 `admin/PosterTemplatesAdmin.vue` — 海报模板管理
  - [x] 表格：名称/场景标签/配色/状态
  - [x] 弹窗：编辑表单（风格描述、配色方案编辑器、参考图上传、预览图）
- [x] **P3.2.5** 新建 `admin/CopyTemplatesAdmin.vue` — 文案模板管理
  - [x] 表格：名称/场景标签/变量列表/状态
  - [x] 弹窗：编辑表单（文案内容编辑、变量说明、场景标签）
- [x] **P3.2.6** 新建 `admin/PptHistoryAdmin.vue` — 生成历史管理
  - [x] 表格：时间/用户/类型（PPT/海报）/产品/操作
  - [x] 筛选：用户 ID/保司/类型/日期范围
  - [x] 操作：查看详情（弹窗）/ 导出 CSV / 删除
- [x] **P3.2.7** 新建 `admin/PptSettingsAdmin.vue` — 系统设置
  - [x] 表单：PPT 历史保留天数 / 海报历史保留天数
  - [x] 保存按钮

- [ ] **P3.2.8** 验证：管理端全部 7 个页面可正常访问和操作
- [ ] **P3.2.9** 验证：非 admin 用户访问管理页面被拒绝

---

## Phase P4：PPT 前端优化 + 历史记录（约 1.5 天）

### P4.1 PPT 前端优化（增量修改现有组件）

- [x] **P4.1.1** PptUpload.vue — 添加骨架屏（`<el-skeleton>` 包裹公司列表和上传区域）
- [x] **P4.1.2** PptUpload.vue — 移动端触屏优化（拖拽区 min-height 120px，点击区域扩大）
- [x] **P4.1.3** PptParsing.vue — 添加骨架屏（解析进度区域）（已有 progress circle 作为加载态）
- [x] **P4.1.4** PptGenerate.vue — 添加骨架屏（样式选择区域）
- [x] **P4.1.5** PptGenerate.vue — 样式卡片 min-width 140px + 按钮 min-height 44px
- [x] **P4.1.6** PptResult.vue — 导出进度反馈（el-progress + axios onDownloadProgress）
- [x] **P4.1.7** 全局 — 表单输入框 font-size 16px（防止 iOS 自动缩放）
- [ ] **P4.1.8** 验证：移动端（768px 以下）PPT 全流程可正常操作

### P4.2 PPT 历史记录 — 后端

- [x] **P4.2.1** 更新 `ppt/routes.py` — 在文件末尾追加历史记录路由（不改已有代码）
- [x] **P4.2.2** GET /ppt/history — 当前用户历史列表（分页 + company_id/action_type/日期筛选）
- [x] **P4.2.3** GET /ppt/history/{id} — 单条历史详情（含 content_snapshot）
- [x] **P4.2.4** POST /ppt/history/{id}/re-download — 重新下载文件
- [x] **P4.2.5** 更新 `ppt/routes.py` generate_ppt — 生成成功后自动写入 history（action_type=export）
- [x] **P4.2.6** 更新 `ppt/routes.py` download_ppt — 下载时自动写入 history（action_type=download）
- [ ] **P4.2.7** 验证：生成 PPT 后 history 表自动新增记录

### P4.3 PPT 历史记录 — 前端

- [x] **P4.3.1** 新建 `pages/PptHistoryPage.vue`
- [x] **P4.3.2** 表格：时间、保司、产品、操作类型、文件、操作（查看/重新下载）
- [x] **P4.3.3** 筛选栏：保司下拉、操作类型下拉、日期范围
- [x] **P4.3.4** 分页：el-pagination
- [x] **P4.3.5** 查看详情弹窗：展示 content_snapshot 的格式化 JSON 视图
- [x] **P4.3.6** 更新 `router/index.ts` — 注册 `/ppt/history` 路由
- [x] **P4.3.7** 更新 `App.vue` 侧边栏 — 功能菜单新增"建议书历史"入口
- [ ] **P4.3.8** 验证：历史记录页面正常显示，查看详情和重新下载可用

---

## Phase P5：海报核心功能 — 后端（约 2.5 天）

### P5.1 小册子解析

- [x] **P5.1.1** 新建 `poster/manual_parser.py` — 小册子解析 prompt
- [x] **P5.1.2** 实现 `parse_manual_pdf(filepath)` — 调用 LLM 提取产品规则（features/currency_options/coverage_highlights）
- [ ] **P5.1.3** 验证：上传小册子 PDF → 解析出结构化 JSON → 更新 products.manual_parsed_rules

### P5.2 计划书解析（复用 extraction.py）

- [x] **P5.2.1** 在 `ppt/extraction.py` 新增 `extract_for_poster(filepath)` 方法
- [x] **P5.2.2** 精简 prompt：只提取海报所需字段（age/gender/currency/sum_assured/premium_term/annual_premium/coverage_period/key_benefits）
- [ ] **P5.2.3** 验证：上传计划书 PDF → 解析出海报所需字段

### P5.3 海报业务逻辑

- [x] **P5.3.1** 新建 `poster/service.py` — PosterService 类
- [x] **P5.3.2** get_reviewed_products — 获取已 reviewed 的产品列表
- [x] **P5.3.3** upload_case — 上传计划书 PDF + 触发解析 → 创建 poster_case_uploads 记录
- [x] **P5.3.4** get_case_upload — 获取解析结果
- [x] **P5.3.5** confirm_case_upload — 人工核对/修正解析数据 → 更新 confirmed_data
- [x] **P5.3.6** get_templates — 获取可用海报模板列表（status=1）
- [x] **P5.3.7** get_copy_templates — 获取可用文案模板列表（status=1）

### P5.4 文案生成

- [x] **P5.4.1** 新建 `poster/copy_generator.py` — CopyGenerator 类
- [x] **P5.4.2** 模板模式 — `generate_template_copy(template, product_rules, customer_data)` — 本地变量替换
- [x] **P5.4.3** AI 模式 — `generate_ai_copy(product_rules, customer_data, style)` — 调用 llm_client.structured_output
- [ ] **P5.4.4** 验证：模板模式返回填充后文案 / AI 模式返回 {headline, body, call_to_action}

### P5.5 海报图片生成

- [x] **P5.5.1** 新建 `poster/image_generator.py` — PosterImageGenerator 类
- [x] **P5.5.2** 实现 `generate(prompt, size)` — 调用 OpenAI images.generate（model=gpt-image-1）
- [x] **P5.5.3** 实现尺寸映射 — 用户尺寸 → API 尺寸（1024x1024 / 1024x1792 / 1792x1024）
- [x] **P5.5.4** 实现 prompt 组装 — 风格 + 配色 + 产品信息 + 客户数据 + 文案 → 完整 prompt
- [x] **P5.5.5** 实现参考图处理 — reference_image 传入 edit 端点或 prompt 描述
- [x] **P5.5.6** 实现降级方案 — API 失败时用 Pillow 生成基础排版图
- [ ] **P5.5.7** 验证：调用 API 返回 PNG 图片 bytes

### P5.6 海报 API 路由

- [x] **P5.6.1** 新建 `poster/routes.py` — poster_bp Blueprint
- [x] **P5.6.2** GET /poster/products — 已 reviewed 产品列表
- [x] **P5.6.3** POST /poster/case-upload — 上传计划书 + 触发解析
- [x] **P5.6.4** GET /poster/case-upload/{id} — 获取解析结果
- [x] **P5.6.5** PUT /poster/case-upload/{id}/confirm — 核对/修正数据
- [x] **P5.6.6** GET /poster/templates — 海报模板列表
- [x] **P5.6.7** GET /poster/copy-templates — 文案模板列表
- [x] **P5.6.8** POST /poster/generate-copy — 生成文案（template/ai 模式）
- [x] **P5.6.9** POST /poster/generate — 生成海报图片（组装 prompt → GPT image API）
- [x] **P5.6.10** GET /poster/download/{record_id} — 下载海报文件
- [x] **P5.6.11** GET /poster/records — 海报生成记录列表
- [x] **P5.6.12** GET /poster/records/{id} — 记录详情

- [ ] **P5.6.13** 验证：完整海报生成流程可用（curl 全链路测试）

---

## Phase P6：海报核心功能 — 前端（约 2 天）

### P6.1 API 封装 + 路由注册

- [x] **P6.1.1** 新建 `utils/poster-api.ts` — 海报功能 API 封装
- [x] **P6.1.2** 更新 `router/index.ts` — 注册 3 个用户端路由（/poster, /poster/history, /ppt/history）
- [x] **P6.1.3** 更新 `App.vue` 侧边栏 — 功能菜单新增"海报生成""海报历史"入口

### P6.2 海报生成向导

- [x] **P6.2.1** 新建 `pages/PosterPage.vue` — 4 步 el-steps 向导容器
- [x] **P6.2.2** 新建 `components/poster/PosterStepProduct.vue` — Step 1: 选择产品
  - [x] 已 reviewed 产品卡片列表（按保司分组）
  - [x] 未 reviewed 产品灰显不可选
  - [x] 选择产品后进入下一步
- [x] **P6.2.3** 新建 `components/poster/PosterStepUpload.vue` — Step 2: 上传计划书
  - [x] 拖拽上传 PDF
  - [x] 解析进度（loading + 进度提示）
  - [x] 解析结果表单：逐字段展示，置信度低的字段高亮
  - [x] 用户可编辑修正每个字段
  - [x] 确认按钮 → 更新 confirmed_data
- [x] **P6.2.4** 新建 `components/poster/PosterStepTemplate.vue` — Step 3: 选模板 + 文案
  - [x] 海报模板卡片网格（含预览图和风格描述）
  - [x] 配色方案展示（从模板继承）
  - [x] 文案模式切换（模板/AI）
  - [x] 模板模式：选择文案模板 → 实时预览填充结果
  - [x] AI 模式：生成文案按钮 → 展示 headline/body/call_to_action → 可编辑
  - [x] 参考图上传（可选，覆盖模板默认图）
- [x] **P6.2.5** 新建 `components/poster/PosterStepPreview.vue` — Step 4: 预览导出
  - [x] "生成海报"按钮 + loading 状态（10-30 秒）
  - [x] 海报图片预览
  - [x] 尺寸选择下拉（4 种预设 + 自定义）
  - [x] 下载按钮

- [ ] **P6.2.6** 验证：完整海报生成流程可用（移动端 + PC 端）

### P6.3 海报历史记录

- [x] **P6.3.1** 新建 `pages/PosterHistoryPage.vue`
- [x] **P6.3.2** 表格：时间、产品、模板、文案模式、操作（查看/重新下载）
- [x] **P6.3.3** 筛选栏：产品下拉、文案模式下拉、日期范围
- [x] **P6.3.4** 分页：el-pagination
- [x] **P6.3.5** 查看详情弹窗：展示文案内容 + 海报缩略图
- [ ] **P6.3.6** 验证：海报历史页面正常显示

---

## Phase P7：合规留痕 + 全链路验证（约 0.5 天）

### P7.1 合规留痕

- [x] **P7.1.1** 海报生成时自动记录：ai_raw_content（AI 原始文案）、copy_content（用户编辑后）、prompt_used（完整 prompt）、reference_image_used
- [x] **P7.1.2** AI 模式下 poster_records 同时保存原始文案和最终文案
- [ ] **P7.1.3** 验证：poster_records 表中合规字段完整填写

### P7.2 全链路验证

- [ ] **P7.2.1** PPT 生成流程不受影响 — 上传/解析/生成/下载全流程正常
- [ ] **P7.2.2** 管理后台 — 保司/产品/模板 CRUD 全部正常
- [ ] **P7.2.3** PPT 历史记录 — 自动生成 + 查询 + 重新下载
- [ ] **P7.2.4** 海报完整流程 — 选产品 → 上传计划书 → 核对 → 选模板 → 生成文案 → 生成海报 → 下载
- [ ] **P7.2.5** 海报历史记录 — 自动生成 + 查询
- [ ] **P7.2.6** 权限验证 — sales 可生成海报但不能管理配置；client 不能访问海报功能
- [ ] **P7.2.7** 移动端验证 — 768px 以下 PPT 和海报全流程可用
- [ ] **P7.2.8** 系统设置 — 修改历史保留天数后生效

---

## 任务统计

| Phase | 任务数 | 预估工时 | 说明 |
|-------|:------:|:--------:|------|
| P1 数据库 + 模型层 | 22 | 1 天 | 迁移脚本 + 6 个模型 + 路由注册 |
| P2 管理后台后端 | 19 | 2 天 | CRUD 服务 + 路由 |
| P3 管理后台前端 | 17 | 2 天 | 7 个管理页面 + 侧边栏 |
| P4 PPT 优化 + 历史 | 18 | 1.5 天 | 骨架屏 + 触屏优化 + 历史记录 |
| P5 海报后端 | 20 | 2.5 天 | 小册子/计划书解析 + 文案 + AI 生图 + API |
| P6 海报前端 | 16 | 2 天 | 4 步向导 + 历史记录 |
| P7 合规 + 验证 | 8 | 0.5 天 | 留痕 + 全链路测试 |
| **合计** | **120** | **~11.5 天** | |