cayden/auto-virtual-tryon

Fork 0

Files

Codex cc03da8a94 Implement FastAPI Temporal MVP pipeline

2026-03-27 00:10:28 +08:00

11 KiB

Raw Permalink Blame History

CODEX 执行文档

0. 任务标题

为图片生产系统实现 FastAPI + Temporal MVP 骨架

1. 任务目标

在现有仓库中搭建一个可运行的最小版本，满足以下目标：

提供 FastAPI 服务
提供 Temporal workflow 和 worker
支持两条流程：
- 低端客户：全自动 auto_basic
- 中端客户：半自动 semi_pro
提供最小接口：
- 创建订单
- 查询订单
- 查询订单资产
- 提交审核结果
代码应可本地启动，结构清晰，便于后续扩展

2. 背景说明

这是一个图片生产流水线系统，面向两类客户：

低端客户

要求批量、快速、低成本。流程为：

选择模特和固定姿势
换装
换场景
基础质检
导出结果

中端客户

要求成图质量更高，允许人工轻审核。流程为：

选择模特和姿势
换装
换场景
衣服材质增强
面部增强
面部融合
自动质检
等待人工审核
通过后导出，或从指定步骤重跑

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. 目录结构要求

严格按以下目录创建：

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 返回：

{"status":"ok"}

9.2 创建订单

POST /api/v1/orders

请求体：

{
  "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

请求体示例：

{
  "decision": "approve",
  "reviewer_id": 77,
  "selected_asset_id": 1001,
  "comment": "通过"
}

或：

{
  "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`

顺序如下：

prepare_model
tryon
scene
qc
export

要求：

每一步都调用 activity
每一步都记录 step 状态
qc 不通过时可直接标记失败
export 完成后写订单成功状态

10.2 中端流程 `MidEndPipelineWorkflow`

顺序如下：

prepare_model
tryon
scene
texture
face
fusion
qc
wait for review signal
approve 后 export
rerun_face 时回到 face
rerun_fusion 时回到 fusion
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 先返回固定结构，例如：

{
  "step_name": "tryon",
  "success": true,
  "asset_id": 10001,
  "uri": "mock://orders/1/tryon/result.png",
  "score": 0.95,
  "message": "mock success"
}

资产可直接写入数据库，不要求真实文件存在。

14. 验收标准

完成后应满足：

uvicorn app.main:app --reload 可以启动
Temporal worker 可以启动
创建低端订单后，workflow 能跑到成功
创建中端订单后，workflow 能停在 waiting_review
提交 approve 后，中端流程可以继续到成功
提交 rerun_face 后，中端流程会回到 face
所有 API 有基础错误处理
代码能通过基础 lint 和测试

15. 输出要求

请按以下顺序产出：

先创建项目目录和核心文件
再实现 domain enums 和 db models
再实现 API schemas 和 routers
再实现 application services
再实现 Temporal client / workflows / activities / worker
最后补充 README，写明本地启动方法

16. README 至少包含

环境要求
安装依赖
启动 FastAPI
启动 Temporal server
启动 worker
调用示例
中端审核 signal 示例

17. 不要做的事

不要擅自改目录结构
不要引入额外复杂框架
不要接入真实第三方 AI 平台
不要写前端页面
不要把所有逻辑塞到一个文件
不要省略测试
不要跳过中端审核 signal

18. 开发优先级

优先级从高到低：

项目骨架
低端 workflow 跑通
中端 workflow + review signal 跑通
API 完整
README 和测试

19. 建议实现顺序

建议你按以下顺序提交代码：

第 1 批：目录、配置、枚举、数据库模型
第 2 批：订单 API、创建订单 service、workflow 启动
第 3 批：低端 workflow + mock activities
第 4 批：中端 workflow + signal
第 5 批：审核 API、README、测试

20. 交付物

最终需要包含：

可运行源码
Alembic 初始迁移
示例 .env.example
README
基础测试

给 Codex 的附加执行指令

请按以下工作方式执行：

先阅读整个任务文档，再开始编码。
先输出一个简短实施计划，再开始改动文件。
每完成一个阶段，就更新一次当前进展。
遇到不明确处时，优先采用最小可运行方案，不要过度设计。
保持每个提交块职责单一，便于审查。
若某一步无法完整实现，先给出可运行的 stub，不要阻塞整体流程。
所有 mock 返回值结构保持一致。
所有关键函数都加类型注解。
尽量保持文件短小，单文件不要过度膨胀。
先保证能跑通，再考虑优雅性。

适合直接发给 Codex 的首条消息

请在当前仓库中实现一个 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，审核后可继续

11 KiB Raw Permalink Blame History Unescape Escape

CODEX 执行文档

0. 任务标题

1. 任务目标

2. 背景说明

低端客户

中端客户

3. 本次范围

4. 技术栈要求

5. 目录结构要求

6. 代码风格要求

7. 核心业务枚举

8. 数据模型要求

orders

assets

review_tasks

workflow_runs

workflow_steps

9. API 需求

9.1 健康检查

9.2 创建订单

9.3 查询订单详情

9.4 查询订单资产

9.5 查询待审核列表

9.6 提交审核结果

9.7 查询工作流状态

10. Workflow 需求

10.1 低端流程 LowEndPipelineWorkflow

10.2 中端流程 MidEndPipelineWorkflow

11. Activity 需求

tryon

scene

texture

face

fusion

qc

export

12. Temporal 实现要求

13. Mock 策略

14. 验收标准

15. 输出要求

16. README 至少包含

17. 不要做的事

18. 开发优先级

19. 建议实现顺序

20. 交付物

给 Codex 的附加执行指令

适合直接发给 Codex 的首条消息

11 KiB

Raw Permalink Blame History

10.1 低端流程 `LowEndPipelineWorkflow`

10.2 中端流程 `MidEndPipelineWorkflow`