MG-03-002 请求任务与日志

状态说明：以当前有效边界为准。供应执行规则与历史实现证据保留；客户身份、售价、结算、全量旧跨仓契约及图像开放计划不代表当前验收范围。

1. 三个不同概念

必须区分：

1. MediaRequest：每次用户调用的统一使用记录；
2. AsyncTask：只有异步请求拥有的可查询任务；
3. Attempt：对某个具体 Supply 的一次 Provider 调用。

同步图像有 MediaRequest 和 Attempt，但没有 AsyncTask。

2. 同步图像

调用链：

鉴权
→ 创建 MediaRequest(in_progress)
→ 调度和容量预占
→ Provider 同步调用
→ 保存输出
→ MediaRequest succeeded/failed
→ 在同一 HTTP 响应返回

对外不返回平台任务 ID，不进入长时间排队。容量不足时快速失败。

同步请求公开状态只有：

succeeded
failed

后台在请求执行期间可以看到 in_progress，但模型广场和文档不能把它描述为异步 任务状态。

3. 异步图像与视频

只有显式异步图像和默认异步视频创建 AsyncTask：

accepted
queued
dispatching
submitted
processing
retrying
succeeded
failed
cancelled
submission_uncertain

建议对外收敛为较少状态：

queued
in_progress
succeeded
failed
cancelled

内部详细状态保留在任务详情和 Attempt 时间线。

视频公开协议可以有不同字段和状态命名，但必须先规范化为同一个 Video Domain Request。billing_mode 是请求能力的一部分，进入幂等指纹、持久请求快照和供给候选 硬过滤：per_second 请求不能选择只有 per_request Cost Rule 的 Supply，反之亦然。

异步时间线由 PostgreSQL media_lifecycle_events 只追加保存。每个 MediaRequest 拥有 从 1 开始单调递增的序号；事件已经提交后禁止更新或删除。事件覆盖：

queued
dispatch
submit
poll
retry
reroute
result
terminal

每次真实 Provider Poll 都追加一条事件，重复轮询不会被压缩成最后状态。第二次 Attempt 同时记录 retry；Supply 或 Channel 变化时再记录 reroute。结果进入平台存储后记录 result，随后才允许写入成功终态。幂等重放只读取现有时间线，不重复追加 queued 或 Provider Attempt。

4. 状态不变量

• MediaRequest、AsyncTask 和 Attempt 终态不可逆；
• Task 成功要求平台能够交付至少一个有效输出；
• Provider 返回成功但结果尚未进入平台存储时仍为 in_progress；
• 重复 Provider 回调、轮询和 Worker 消息不得创建重复输出；
• Attempt 固定绑定 Supply、Credential Version 和 Cost Rule Version；
• 停用 Supply 不改变已提交 Attempt 的查询归属。

5. 统一使用记录页面

列表字段：

请求时间
请求 ID
用户/API Key
图像/视频
同步/异步
公开模型
状态
是否重试
是否降级
排队时间
处理时间
输出数量

状态徽标：

queued
in_progress
retrying
succeeded
failed
cancelled

degraded、submission_uncertain、content_error、supply_error 作为额外徽标。

6. 详情

普通用户可见：

• 规范化请求摘要；
• 公开模型和请求能力；
• 当前状态和时间线；
• 是否发生重试或降级；
• 实际能力与被移除/降低内容；
• 输出；
• 用户可理解的错误。

普通用户时间线只包含序号、公开事件、公开状态、Attempt 次数和发生时间，不包含 Channel、Supply、Provider Task、成本、内部 URL、Prompt、素材或 Provider 错误正文。

管理员额外可见：

• Channel、Supply 和 Provider 模型；
• Provider Task ID；
• 每次 Attempt；
• 路由候选及排除原因；
• 健康与容量快照；
• Quote、累计成本和实际成本；
• 原始 Provider 错误的脱敏版本；
• 告警和人工操作。

管理员时间线可以额外包含 Attempt、Supply、Channel 的稳定 ID，以及安全错误类别、 范围和代码；Provider Task、Credential、URL、Prompt 和 Provider 响应正文仍不进入 时间线。

普通用户不能看到 Provider Credential、内部网络地址或其他用户信息。

7. 幂等

生成接口支持 Idempotency-Key：

• 同 API Key、同幂等 Key、同请求指纹返回同一结果或任务；
• 同 API Key、同幂等 Key、不同请求返回 409；
• 同步图像重放已经完成的请求时返回保存的结果；
• 正在执行的同步图像不能创建第二次 Provider 调用；
• 异步请求返回同一 AsyncTask；
• 幂等窗口首版至少 24 小时。

8. 输出

• 异步输入素材需要复制到平台临时存储，保证排队和重试时仍可访问；
• Provider 输出需要转存到平台控制的 S3/R2；
• 数据库保存稳定 Asset ID，不保存短期签名 URL；
• /content/{asset_id} 可以使用 307 短期签名跳转；
• 对不兼容重定向的客户提供显式流式代理模式；
• HEAD、单段 Range、URL 过期重新签名和对象过期必须有稳定语义。