# 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 任务失败或额度不足时，原图上传结果保持成功状态。