feat: 新增相册自动修图与OTG状态预览

支持相册修图配置、模板选择和传输模式选择；上传后自动提交修图并展示状态角标及精修预览。补充接口文档与相关测试。
2026-08-27 16:03:40 +08:00
parent 9fce6ef713
commit d04641b623
17 changed files with 2523 additions and 26 deletions
@@ -0,0 +1,92 @@
+# AI 自动修图后端接口改造（精简版）
+
+## 一、需要修改的接口
+
+### 1. 创建相册
+
+`POST /api/yf-handset-app/photog/travel-album/create`
+
+请求新增：
+
+```json
+{
+  "auto_retouch_config": {
+    "enabled": true,
+    "refined_template_id": 12
+  }
+}
+```
+
+规则：
+
+- `enabled = true` 时，`refined_template_id` 必填且模板必须有效。
+- `enabled = false` 时，服务端将 `refined_template_id` 规范化为 `null`。
+- 响应返回完整 `auto_retouch_config`。
+
+### 2. 相册详情和列表
+
+- `GET /api/yf-handset-app/photog/travel-album/info`
+- `GET /api/yf-handset-app/photog/travel-album/list`
+
+每个相册新增响应字段：
+
+```json
+{
+  "auto_retouch_config": {
+    "enabled": true,
+    "refined_template_id": 12
+  }
+}
+```
+
+规则：
+
+- 历史相册没有配置时按关闭状态返回。
+
+## 二、需要新增的接口
+
+### 更新相册自动修图配置
+
+`POST /api/yf-handset-app/photog/travel-album/auto-retouch-config`
+
+请求：
+
+```json
+{
+  "user_equity_travel_id": 88,
+  "enabled": true,
+  "refined_template_id": 12
+}
+```
+
+成功响应 `data`：
+
+```json
+{
+  "enabled": true,
+  "refined_template_id": 12
+}
+```
+
+规则：
+
+- 返回服务端规范化后的完整配置。
+- 多设备同时修改时采用最后一次写入生效。
+
+## 三、无需新增但需要确保可用的接口
+
+- `POST .../upload-material`：成功后必须返回稳定的服务端素材 `id`。
+- `GET .../ai-retouch-templates`：直接使用现有 `refined_templates`，无需新增模板描述字段。
+- `POST .../ai-retouch`：请求和响应保持现状，不增加 `client_request_id`。
+- `GET .../ai-retouch-job-info`：支持按任务批次查询 `queued / processing / succeeded / partially_succeeded / failed / canceled` 状态。
+
+客户端会在 `upload-material` 成功后提交 AI 任务，并在前台每 8 秒查询任务状态。AI 额度不足、模板失效或任务失败都不能回滚原图上传结果。
+
+由于 `ai-retouch` 不提供幂等能力，客户端在请求超时、断网等结果不确定的情况下不得自动重复提交；只能先同步素材或任务状态。若无法确认是否已创建任务，需提示用户“提交状态未知”，避免直接重试导致重复任务或重复扣额。
+
+## 四、后端验收重点
+
+1. 创建、详情和列表中的配置字段保持一致。
+2. 配置关闭时服务端将 `refined_template_id` 规范化为 `null`。
+3. 原图登记成功后可以使用现有 `ai-retouch` 接口创建单素材精修任务。
+4. AI 任务失败或额度不足时，原图上传结果保持成功状态。