Implement FastAPI Temporal MVP pipeline

codex_task.md

@@ -0,0 +1,543 @@
+# CODEX 执行文档
+
+## 0. 任务标题
+为图片生产系统实现 FastAPI + Temporal MVP 骨架
+
+## 1. 任务目标
+在现有仓库中搭建一个可运行的最小版本，满足以下目标：
+
+- 提供 FastAPI 服务
+- 提供 Temporal workflow 和 worker
+- 支持两条流程：
+  - 低端客户：全自动 `auto_basic`
+  - 中端客户：半自动 `semi_pro`
+- 提供最小接口：
+  - 创建订单
+  - 查询订单
+  - 查询订单资产
+  - 提交审核结果
+- 代码应可本地启动，结构清晰，便于后续扩展
+
+## 2. 背景说明
+这是一个图片生产流水线系统，面向两类客户：
+
+### 低端客户
+要求批量、快速、低成本。
+流程为：
+
+1. 选择模特和固定姿势
+2. 换装
+3. 换场景
+4. 基础质检
+5. 导出结果
+
+### 中端客户
+要求成图质量更高，允许人工轻审核。
+流程为：
+
+1. 选择模特和姿势
+2. 换装
+3. 换场景
+4. 衣服材质增强
+5. 面部增强
+6. 面部融合
+7. 自动质检
+8. 等待人工审核
+9. 通过后导出，或从指定步骤重跑
+
+## 3. 本次范围
+只实现 **MVP 骨架**，不要求接入真实 AI 平台。
+
+本次只需要：
+
+- FastAPI 项目结构
+- Temporal workflow / activity / worker 结构
+- Pydantic 请求响应模型
+- 先用 mock activity 代替真实图像处理
+- 数据层先可用 SQLite + SQLAlchemy
+- 资产先用本地路径或假 URI
+- review signal 可跑通
+
+本次不需要：
+
+- 真正的换装算法
+- 真正的图像增强
+- 真实对象存储
+- 权限系统
+- 完整后台页面
+- 第三方平台集成
+
+## 4. 技术栈要求
+- Python 3.11+
+- FastAPI
+- Uvicorn
+- SQLAlchemy 2.x
+- Pydantic v2
+- Temporal Python SDK
+- Alembic
+- pytest
+
+## 5. 目录结构要求
+严格按以下目录创建：
+
+```text
+app/
+  main.py
+  config/
+    settings.py
+  api/
+    routers/
+      health.py
+      orders.py
+      assets.py
+      reviews.py
+      workflows.py
+    schemas/
+      order.py
+      asset.py
+      review.py
+      workflow.py
+  application/
+    services/
+      order_service.py
+      workflow_service.py
+      review_service.py
+      asset_service.py
+  domain/
+    enums.py
+    models/
+      order.py
+      asset.py
+      review_task.py
+      workflow_run.py
+      workflow_step.py
+  infra/
+    db/
+      base.py
+      session.py
+      models/
+        order.py
+        asset.py
+        review_task.py
+        workflow_run.py
+        workflow_step.py
+    temporal/
+      client.py
+      task_queues.py
+  workers/
+    runner.py
+    workflows/
+      types.py
+      low_end_pipeline.py
+      mid_end_pipeline.py
+    activities/
+      tryon_activities.py
+      scene_activities.py
+      texture_activities.py
+      face_activities.py
+      fusion_activities.py
+      qc_activities.py
+      export_activities.py
+      review_activities.py
+tests/
+```
+
+## 6. 代码风格要求
+- 使用类型注解
+- 使用 async 风格
+- 保持模块边界清晰
+- route 中不要写业务逻辑
+- workflow 中不要直接访问数据库
+- activity 中允许 I/O 和 mock 处理
+- 所有核心函数写 docstring
+- 所有枚举统一放在 `domain/enums.py`
+
+## 7. 核心业务枚举
+实现以下枚举：
+
+- `CustomerLevel`: `low`, `mid`
+- `ServiceMode`: `auto_basic`, `semi_pro`
+- `OrderStatus`: `created`, `running`, `waiting_review`, `succeeded`, `failed`, `cancelled`
+- `WorkflowStepName`: `prepare_model`, `tryon`, `scene`, `texture`, `face`, `fusion`, `qc`, `export`, `review`
+- `ReviewDecision`: `approve`, `rerun_scene`, `rerun_face`, `rerun_fusion`, `reject`
+
+## 8. 数据模型要求
+
+### orders
+字段至少包含：
+- id
+- customer_level
+- service_mode
+- status
+- model_id
+- pose_id
+- garment_asset_id
+- scene_ref_asset_id
+- final_asset_id
+- created_at
+- updated_at
+
+### assets
+字段至少包含：
+- id
+- order_id
+- asset_type
+- step_name
+- uri
+- metadata_json
+- created_at
+
+### review_tasks
+字段至少包含：
+- id
+- order_id
+- status
+- decision
+- reviewer_id
+- selected_asset_id
+- comment
+- created_at
+- updated_at
+
+### workflow_runs
+字段至少包含：
+- id
+- order_id
+- workflow_id
+- workflow_type
+- status
+- current_step
+- created_at
+- updated_at
+
+### workflow_steps
+字段至少包含：
+- id
+- workflow_run_id
+- step_name
+- step_status
+- input_json
+- output_json
+- error_message
+- started_at
+- ended_at
+
+## 9. API 需求
+
+### 9.1 健康检查
+`GET /healthz`
+返回：
+```json
+{"status":"ok"}
+```
+
+### 9.2 创建订单
+`POST /api/v1/orders`
+
+请求体：
+```json
+{
+  "customer_level": "low",
+  "service_mode": "auto_basic",
+  "model_id": 101,
+  "pose_id": 3,
+  "garment_asset_id": 9001,
+  "scene_ref_asset_id": 8001
+}
+```
+
+行为：
+- 创建订单
+- 创建 workflow_run
+- 启动 Temporal workflow
+- 返回 order_id 和 workflow_id
+
+### 9.3 查询订单详情
+`GET /api/v1/orders/{order_id}`
+
+返回：
+- 基本订单信息
+- 当前状态
+- 当前步骤
+- 最终资产（如果有）
+
+### 9.4 查询订单资产
+`GET /api/v1/orders/{order_id}/assets`
+
+返回该订单相关所有资产列表。
+
+### 9.5 查询待审核列表
+`GET /api/v1/reviews/pending`
+
+返回所有 `waiting_review` 的订单。
+
+### 9.6 提交审核结果
+`POST /api/v1/reviews/{order_id}/submit`
+
+请求体示例：
+```json
+{
+  "decision": "approve",
+  "reviewer_id": 77,
+  "selected_asset_id": 1001,
+  "comment": "通过"
+}
+```
+
+或：
+```json
+{
+  "decision": "rerun_face",
+  "reviewer_id": 77,
+  "comment": "面部不自然，重跑 face"
+}
+```
+
+行为：
+- 记录 review_task
+- 向对应 workflow 发送 signal
+
+### 9.7 查询工作流状态
+`GET /api/v1/workflows/{order_id}`
+
+返回：
+- workflow_id
+- workflow_status
+- current_step
+- step 列表
+
+## 10. Workflow 需求
+
+### 10.1 低端流程 `LowEndPipelineWorkflow`
+顺序如下：
+
+1. prepare_model
+2. tryon
+3. scene
+4. qc
+5. export
+
+要求：
+- 每一步都调用 activity
+- 每一步都记录 step 状态
+- qc 不通过时可直接标记失败
+- export 完成后写订单成功状态
+
+### 10.2 中端流程 `MidEndPipelineWorkflow`
+顺序如下：
+
+1. prepare_model
+2. tryon
+3. scene
+4. texture
+5. face
+6. fusion
+7. qc
+8. wait for review signal
+9. approve 后 export
+10. rerun_face 时回到 face
+11. rerun_fusion 时回到 fusion
+12. rerun_scene 时回到 scene
+
+要求：
+- 使用 workflow signal 实现人工审核回流
+- 在等待审核时，订单状态应更新为 `waiting_review`
+- 最终通过后导出
+
+## 11. Activity 需求
+先全部实现为 mock 版本，统一返回假结果。
+
+### tryon
+输入：
+- order_id
+- source asset refs
+
+输出：
+- 新 asset uri
+- step result
+
+### scene
+输入：
+- 上一步结果
+
+输出：
+- 场景替换后 asset
+
+### texture
+输入：
+- 上一步结果
+
+输出：
+- 材质增强 asset
+
+### face
+输入：
+- 上一步结果
+
+输出：
+- 面部增强 asset
+
+### fusion
+输入：
+- 主图 + face 输出
+
+输出：
+- 融合后的 asset
+
+### qc
+输入：
+- 当前图
+
+输出：
+- score
+- pass/fail
+- candidate assets 可先只返回一张
+
+### export
+输入：
+- 最终通过的 asset
+
+输出：
+- final asset
+
+## 12. Temporal 实现要求
+- workflow 输入使用 dataclass
+- workflow id 使用 `order-{order_id}`
+- task queue 至少拆成：
+  - `image-pipeline-control`
+  - `image-pipeline-image-gen`
+  - `image-pipeline-post-process`
+  - `image-pipeline-qc`
+  - `image-pipeline-export`
+- activity 配置合理的 `start_to_close_timeout`
+- 为常见 activity 加 retry policy
+
+## 13. Mock 策略
+为了让系统可运行，所有 activity 先返回固定结构，例如：
+
+```json
+{
+  "step_name": "tryon",
+  "success": true,
+  "asset_id": 10001,
+  "uri": "mock://orders/1/tryon/result.png",
+  "score": 0.95,
+  "message": "mock success"
+}
+```
+
+资产可直接写入数据库，不要求真实文件存在。
+
+## 14. 验收标准
+完成后应满足：
+
+1. `uvicorn app.main:app --reload` 可以启动
+2. Temporal worker 可以启动
+3. 创建低端订单后，workflow 能跑到成功
+4. 创建中端订单后，workflow 能停在 `waiting_review`
+5. 提交 `approve` 后，中端流程可以继续到成功
+6. 提交 `rerun_face` 后，中端流程会回到 `face`
+7. 所有 API 有基础错误处理
+8. 代码能通过基础 lint 和测试
+
+## 15. 输出要求
+请按以下顺序产出：
+
+1. 先创建项目目录和核心文件
+2. 再实现 domain enums 和 db models
+3. 再实现 API schemas 和 routers
+4. 再实现 application services
+5. 再实现 Temporal client / workflows / activities / worker
+6. 最后补充 README，写明本地启动方法
+
+## 16. README 至少包含
+- 环境要求
+- 安装依赖
+- 启动 FastAPI
+- 启动 Temporal server
+- 启动 worker
+- 调用示例
+- 中端审核 signal 示例
+
+## 17. 不要做的事
+- 不要擅自改目录结构
+- 不要引入额外复杂框架
+- 不要接入真实第三方 AI 平台
+- 不要写前端页面
+- 不要把所有逻辑塞到一个文件
+- 不要省略测试
+- 不要跳过中端审核 signal
+
+## 18. 开发优先级
+优先级从高到低：
+
+1. 项目骨架
+2. 低端 workflow 跑通
+3. 中端 workflow + review signal 跑通
+4. API 完整
+5. README 和测试
+
+## 19. 建议实现顺序
+建议你按以下顺序提交代码：
+
+- 第 1 批：目录、配置、枚举、数据库模型
+- 第 2 批：订单 API、创建订单 service、workflow 启动
+- 第 3 批：低端 workflow + mock activities
+- 第 4 批：中端 workflow + signal
+- 第 5 批：审核 API、README、测试
+
+## 20. 交付物
+最终需要包含：
+
+- 可运行源码
+- Alembic 初始迁移
+- 示例 `.env.example`
+- README
+- 基础测试
+
+---
+
+## 给 Codex 的附加执行指令
+
+请按以下工作方式执行：
+
+1. 先阅读整个任务文档，再开始编码。
+2. 先输出一个简短实施计划，再开始改动文件。
+3. 每完成一个阶段，就更新一次当前进展。
+4. 遇到不明确处时，优先采用最小可运行方案，不要过度设计。
+5. 保持每个提交块职责单一，便于审查。
+6. 若某一步无法完整实现，先给出可运行的 stub，不要阻塞整体流程。
+7. 所有 mock 返回值结构保持一致。
+8. 所有关键函数都加类型注解。
+9. 尽量保持文件短小，单文件不要过度膨胀。
+10. 先保证能跑通，再考虑优雅性。
+
+---
+
+## 适合直接发给 Codex 的首条消息
+
+```md
+请在当前仓库中实现一个 FastAPI + Temporal 的 MVP 图片流水线系统。
+
+目标：
+- 支持低端全自动 auto_basic
+- 支持中端半自动 semi_pro
+- 提供创建订单、查询订单、查询资产、提交审核、查询 workflow 状态接口
+- 使用 SQLite + SQLAlchemy + FastAPI + Temporal Python SDK
+- 真实图像处理先全部 mock
+
+要求：
+- 严格按我提供的目录结构创建文件
+- route 不写业务逻辑
+- workflow 只做编排
+- activity 做 mock 执行
+- 中端流程必须支持 review signal，并支持 rerun_face / rerun_fusion / rerun_scene
+- 输出 README、.env.example、alembic 初始迁移、基础测试
+
+交付标准：
+- API 可启动
+- worker 可启动
+- 低端流程可跑通
+- 中端流程可停在 waiting_review，审核后可继续
+```
+