# 回忆录图片状态契约

本文档描述章节图片资产在接口层的字段语义，供后端、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` 自动延长轮询窗口