# 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，审核后可继续
```