baodan/docs/workspace-implementation-log.md

工作区改造实施记录

实施日期

2026-07-28

已完成内容（阶段 1 + 阶段 2 核心）

1. 数据库迁移（阶段 1）

• 文件: api/insurance/db/migrate_022.py
• 扩展 insurance_ppt_sessions 表：新增 title、workflow_step、draft_options_json、draft_revision、generated_revision、latest_task_id、latest_output_path、archived_at 字段
• 扩展 poster_records 表：新增 title、workflow_step、draft_status、draft_revision、generated_revision、latest_task_id、archived_at 字段
• 新建 insurance_generation_tasks 表：统一任务执行表，含状态机、进度、快照、幂等键等

2. 数据模型更新（阶段 1）

• PptSession (api/insurance/models/ppt_session.py)：添加工作区字段和 to_dict 输出
• PosterRecord (api/insurance/models/poster_record.py)：添加工作区字段和 to_dict 输出，修复 Integer 导入
• GenerationTask (api/insurance/models/generation_task.py)：新建统一任务模型

3. Celery 任务模块（阶段 2）

• celery_tasks.py (api/insurance/generation/celery_tasks.py)

  • parse_ppt_task: PPT PDF 解析任务
  • generate_ppt_task: PPT 生成任务
  • parse_poster_task: 海报计划书解析任务
  • generate_poster_task: 海报图片生成任务
  • 所有任务通过数据库状态机保证幂等（queued → running → done/failed）
  • 使用 @shared_task 装饰器自动注册到 Celery

• task_service.py (api/insurance/generation/task_service.py)

  • create_task(): 创建任务并提交到 Celery，含幂等检查和并发控制
  • list_active_tasks(): 查询活跃任务（任务坞用）
  • list_tasks(): 查询任务列表（任务中心用）
  • get_task(): 获取任务详情
  • cancel_task(): 取消排队中的任务
  • hide_task_from_dock(): 从任务坞隐藏任务

4. 工作区 API（阶段 1 + 2）

• routes.py (api/insurance/generation/routes.py)
  • PPT 工作区：列表、详情、重命名、归档、取消归档
  • 海报工作区：列表、详情、重命名、归档
  • 统一任务：列表、活跃任务（坞）、详情、取消、隐藏

5. 路由注册

• routes.py (api/insurance/routes.py)
  • 注册 workspace Blueprint 到 /insurance/workspace 前缀
  • 添加 Celery 任务注册函数 _register_celery_tasks()

6. 服务层改造

• PPT routes (api/insurance/ppt/routes.py)

  • parse_session: 改为通过 task_service 创建异步任务
  • generate_ppt: 改为异步任务，返回 202 Accepted + taskId

• Poster service (api/insurance/poster/service.py)

  • generate_poster: 改为通过 task_service 创建 Celery 任务

待完成内容

阶段 2 补全

• Worker 心跳更新（_update_task_status 每次更新 heartbeat_at）
• 过期任务自动恢复（recover_stale_tasks 启动时调用）

阶段 3：前端刷新恢复与多工作区（3-4 人日）

• 新增工作区路由（/ppt/:sessionId, /poster/:recordId）
• 状态驱动当前步骤（根据 workflow_step 自动跳转）
• 恢复草稿和解析结果（usePptWorkspace / usePosterWorkspace composable）
• 工作区列表入口页（WorkspaceListPage.vue + /ppt/workspaces, /poster/workspaces）
• 任务复制（后端 copy 接口 + 前端复制操作）

阶段 4：全局任务坞与任务中心（2-3 人日）

• 新增 GenerationTaskDock 组件（浮动面板，5s 轮询）
• 新增任务中心页面（TasksPage.vue）
• 侧边栏添加"任务中心"入口
• 未读完成和失败提示（el-badge 通知气泡）
• 移动端抽屉适配（已在 App.vue 移动端菜单中添加任务中心入口）

阶段 5：版本化编辑（2-3 人日）

• 草稿自动保存（useAutoSave composable + 后端 PATCH 接口）
• 乐观锁（expected_revision 冲突检测）
• 输入快照（已在 GenerationTask 模型中实现）
• 草稿版本和成品版本（draft_revision / generated_revision）
• 未生成修改提示（DraftIndicator 组件）
• 输出文件按 task 隔离（PPT: outputs/ppt/{uid}/{task_id}/, 海报: outputs/posters/{task_id}/）

阶段 6：测试与灰度（2-3 人日）

• 单元测试
• Celery 集成测试
• 多任务端到端测试
• Worker 中断测试
• 多标签页测试
• 权限和文件安全测试
• 数据迁移和旧历史兼容测试

注意事项

1. Celery Worker 启动验证：部署后需要验证 insurance.parse_ppt、insurance.generate_ppt、insurance.parse_poster、insurance.generate_poster 四个任务是否已注册到 Worker
2. 数据库迁移：部署前需要执行 migrate_022.py 迁移
3. 向后兼容：旧的 PPT 解析（parse_worker.py）和海报任务（poster/tasks.py）保留作为降级方案
4. 前端适配：前端需要适配新的 202 响应和任务轮询逻辑