# 工作区改造实施记录

## 实施日期
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 补全
- [x] Worker 心跳更新（_update_task_status 每次更新 heartbeat_at）
- [x] 过期任务自动恢复（recover_stale_tasks 启动时调用）

### 阶段 3：前端刷新恢复与多工作区（3-4 人日）
- [x] 新增工作区路由（/ppt/:sessionId, /poster/:recordId）
- [x] 状态驱动当前步骤（根据 workflow_step 自动跳转）
- [x] 恢复草稿和解析结果（usePptWorkspace / usePosterWorkspace composable）
- [x] 工作区列表入口页（WorkspaceListPage.vue + /ppt/workspaces, /poster/workspaces）
- [x] 任务复制（后端 copy 接口 + 前端复制操作）

### 阶段 4：全局任务坞与任务中心（2-3 人日）
- [x] 新增 GenerationTaskDock 组件（浮动面板，5s 轮询）
- [x] 新增任务中心页面（TasksPage.vue）
- [x] 侧边栏添加"任务中心"入口
- [x] 未读完成和失败提示（el-badge 通知气泡）
- [x] 移动端抽屉适配（已在 App.vue 移动端菜单中添加任务中心入口）

### 阶段 5：版本化编辑（2-3 人日）
- [x] 草稿自动保存（useAutoSave composable + 后端 PATCH 接口）
- [x] 乐观锁（expected_revision 冲突检测）
- [x] 输入快照（已在 GenerationTask 模型中实现）
- [x] 草稿版本和成品版本（draft_revision / generated_revision）
- [x] 未生成修改提示（DraftIndicator 组件）
- [x] 输出文件按 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 响应和任务轮询逻辑