ai/docs/system_b/12_任务队列_错误重试_稳定性设计.md

# 12_任务队列_错误重试_稳定性设计

## 1. 文档目标

本文档定义系统 B 的任务队列、状态机、幂等、重试、错误码、恢复机制和并发控制。

## 2. 为什么必须队列化

系统 B 的生成链路长且耗时：

```text
照片检测
人物档案
方案生成
预览图
正式图
图片质检
TTS
字幕
视频合成
最终质检
人工审核
```

如果同步执行，容易导致：

- 请求超时
- 用户重复点击
- 服务阻塞
- 失败无法恢复
- 成本无法追踪

## 3. 队列划分

```text
photo_check_queue：照片检测
text_queue：方案、文案、Prompt
image_queue：预览图、正式图
video_queue：AI 图生视频
voice_queue：TTS
audio_queue：BGM 处理
ffmpeg_queue：视频合成
qc_queue：质量检测
cleanup_queue：文件清理
notification_queue：通知
```

## 4. 任务状态

```text
pending：等待执行
running：执行中
success：成功
failed：失败
retrying：重试中
cancelled：取消
manual_required：需要人工处理
```

## 5. 任务字段

每个任务必须有：

```text
task_id
project_id
task_type
provider_id
status
input_json
input_hash
output_asset_id
provider_request_id
retry_count
max_retry
cost_estimate
cost_actual
error_code
error_message
created_at
started_at
finished_at
```

## 6. 幂等设计

幂等 key：

```text
project_id + task_type + input_hash
```

规则：

- 如果已有成功任务，直接返回成功结果。
- 如果已有运行任务，返回当前任务状态。
- 如果已有失败任务，按重试规则处理。
- 同一请求不能重复创建多个高成本任务。

## 7. 项目级锁

某些任务必须串行：

- 创作方案生成
- 视频合成
- 最终交付

使用 Redis lock：

```text
lock:project:{project_id}:workflow
```

避免并发触发导致状态混乱。

## 8. 重试策略

默认：

```text
max_retry = 3
backoff = exponential
```

例如：

```text
第 1 次失败：30 秒后重试
第 2 次失败：2 分钟后重试
第 3 次失败：5 分钟后重试
```

不可重试错误：

- 用户照片不合格
- 余额不足
- 授权未确认
- 内容审核不通过
- 套餐限制冲突

可重试错误：

- Provider 超时
- 网络错误
- 速率限制
- 临时服务异常
- FFmpeg 临时失败

## 9. 失败转人工

满足任一条件转人工：

- 同一任务连续失败超过 max_retry
- 图片质检连续失败
- 人像一致性评分过低
- 视频合成失败
- 审核 warning
- 高端定制项目

状态：

```text
manual_required
```

## 10. 并发限制

### 用户级

```text
每个用户最多同时 1 个正式生成项目
```

### 项目级

```text
每个项目最多同时 N 个图片任务
视频合成任务只能 1 个
```

### Provider 级

```text
按 Provider 设置 QPS 和并发数
```

## 11. 队列优先级

优先级建议：

1. 高端定制项目
2. 已支付正式生成
3. 预览生成
4. 免费预览
5. 清理任务

## 12. 错误码设计

| 错误码 | 含义 |
|---|---|
| TASK_TIMEOUT | 任务超时 |
| PROVIDER_TIMEOUT | Provider 超时 |
| PROVIDER_RATE_LIMIT | Provider 限流 |
| PROVIDER_ERROR | Provider 错误 |
| INPUT_INVALID | 输入参数错误 |
| PHOTO_QUALITY_FAIL | 照片质量不合格 |
| PAYMENT_REQUIRED | 需要支付 |
| QUOTA_NOT_ENOUGH | 额度不足 |
| MODERATION_REJECTED | 审核不通过 |
| FFMPEG_FAILED | 视频合成失败 |
| STORAGE_FAILED | 存储失败 |
| UNKNOWN_ERROR | 未知错误 |

## 13. 任务恢复

服务重启后：

1. 扫描 running 超时任务。
2. 判断是否有 Provider request_id。
3. 查询 Provider 状态，能恢复则恢复。
4. 无法恢复则标记 failed 并按规则重试。

## 14. 状态一致性

项目状态由 WorkflowService 统一更新。不要让 Worker 随意改最终状态。

Worker 只上报：

```text
task success/failed
output asset
progress
error
```

WorkflowService 根据任务完成情况推进项目状态。

## 15. 防重复点击

前端：按钮 loading，防抖。  
后端：幂等 key + 状态校验。

例如：

- 已在 preview_generating，不允许再次 generate-preview。
- 已 payment_paid，不允许重复创建同一套餐订单。

## 16. 任务超时设置

建议：

```text
photo_check：2 分钟
text_generate：3 分钟
image_generate：10 分钟
video_generate：30 分钟
voice_generate：5 分钟
ffmpeg_render：30 分钟
final_qc：10 分钟
```

## 17. 告警

触发告警：

- 失败任务数超过阈值
- 某 Provider 连续失败
- 队列积压过多
- 视频合成失败率过高
- 单项目成本异常
- 磁盘/MinIO 容量不足

## 18. 日志要求

每个任务记录：

- 输入摘要
- 输出摘要
- Provider
- 成本
- 耗时
- 错误
- 重试次数

敏感数据脱敏保存。

## 19. V3 真人动态视频队列增量

新增队列：

```text
identity_anchor_queue：身份锚点生成
face_consistency_queue：本人相似度检查
motion_portrait_queue：动态写真轻动效
real_video_clip_queue：真人动态视频片段
video_clip_qc_queue：视频片段质检
lipsync_queue：口型同步
```

隔离原则：

- `real_video_clip_queue` 必须独立限流，避免高成本视频任务堵住图片和普通合成。
- `lipsync_queue` 独立限流，失败不影响基础旁白字幕交付。
- `face_consistency_queue` 可优先级较高，因为它决定是否能继续生成。

V3 超时建议：

```text
identity_anchor_generate：10 分钟
face_consistency_check：3 分钟
motion_portrait_generate：20 分钟
real_video_clip_generate：60 分钟
video_clip_qc：10 分钟
lipsync_generate：45 分钟
```

V3 错误码：

```text
IDENTITY_ANCHOR_NOT_CONFIRMED
FACE_CONSISTENCY_LOW
REAL_VIDEO_PROVIDER_DISABLED
REAL_VIDEO_CONFIRMATION_REQUIRED
REAL_VIDEO_COST_LIMIT_EXCEEDED
REAL_VIDEO_CLIP_FAILED
VIDEO_CLIP_QC_FAILED
LIPSYNC_FAILED
MINOR_MANUAL_REVIEW_REQUIRED
```

真实视频任务失败时：

1. 记录 Provider 错误。
2. 标记片段 failed 或 needs_retry。
3. 不回落 mock 假成功。
4. 不重复扣用户额度。
5. 用户端显示失败原因和重试入口。