life-echo/docs/memoir-image-status-contract.md

回忆录图片状态契约

本文档描述章节图片资产在接口层的字段语义，供后端、Android 客户端和后续其他前端实现统一使用。

字段说明

• status
  • pending: 等待生成
  • processing: 正在生成
  • completed: 生成完成
  • failed: 生成失败
• url
  • 仅当图片当前可直接展示时才应为非空
  • 私有 COS 桶签名失败时，必须置空，不能回退为未签名的原始 COS URL
• retryable
  • null: 当前不是失败态，或该字段不适用
  • true: 失败但仍可重试
  • false: 失败且不可重试，属于永久失败
• error
  • 面向调试和展示的错误信息

推荐组合语义

status	url	retryable	语义
pending	null	null	任务尚未开始或等待处理
processing	null	null	图片正在生成
completed	非空	null	图片可直接展示
completed	null	null	图片已完成但当前不可投递，例如私有桶签名失败
failed	null	true	本次失败可重试
failed	null	false	永久失败，应明确展示终态

客户端处理建议

• pending / processing: 显示“图片生成中”
• completed 且 url 非空: 正常展示图片
• completed 且 url 为空: 显示“图片暂不可用”
• failed 且 retryable=true: 显示“图片生成失败，稍后重试”
• failed 且 retryable=false: 显示“图片生成失败，暂不可恢复”

约束

• 后端在规范化图片资产时必须保留 retryable
• 非失败态不应输出 retryable=true/false
• 客户端轮询是否继续，仍以工作态 pending/processing 为准，不因 failed + retryable=true 自动延长轮询窗口