修复回忆录图片重试状态透传与前端展示

docs/memoir-image-status-contract.md

@@ -0,0 +1,45 @@
+# 回忆录图片状态契约
+
+本文档描述章节图片资产在接口层的字段语义，供后端、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` 自动延长轮询窗口