Initial AI manga platform

2026-06-15 17:45:28 +08:00
commit 7a8191650f
267 changed files with 105987 additions and 0 deletions
@@ -0,0 +1,337 @@
+# 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. 用户端显示失败原因和重试入口。