544 lines
11 KiB
Markdown
544 lines
11 KiB
Markdown
# 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，审核后可继续
|
||
```
|
||
|