# AI 重新修图接口优化需求

## 1. 背景

图片预览页面支持用户在“原图”Tab 上重新选择修图模板。

用户可能只生成过一种关联图片，例如之前仅生成了“原图精修”，尚未生成“氛围感”图片。此时用户重新修图时，可以同时选择：

- 原图精修模板
- 氛围感修图模板

客户端会调用现有 `ai-reretouch` 接口，并通过 `type = 3` 提交两个模板，希望一次创建两个修图输出任务。

## 2. 问题复现

### 前置状态

- 原图素材 ID：`702`
- 原 AI 修图批次 ID：`61`
- 已存在并完成：原图精修
- 从未生成：氛围感图片

### 请求

```http
POST /api/yf-handset-app/photog/travel-album/ai-reretouch
```

```json
{
  "ai_retouch_batch_id": 61,
  "id": 702,
  "type": 3,
  "refined_template_id": 2,
  "atmosphere_template_id": 14
}
```

字段含义：

| 字段 | 值 | 说明 |
| --- | ---: | --- |
| `ai_retouch_batch_id` | `61` | 原 AI 修图批次 ID |
| `id` | `702` | 原图素材 ID |
| `type` | `3` | 同时处理精修和氛围感 |
| `refined_template_id` | `2` | 本次选择的精修模板 |
| `atmosphere_template_id` | `14` | 本次选择的氛围感模板 |

### 当前响应

```json
{
  "code": 100099,
  "data": [],
  "msg": "仅已完成修图的照片可重新修图",
  "time": "2026-08-14 17:41:17"
}
```

## 3. 当前问题

从响应判断，后端可能在 `type = 3` 时要求精修图和氛围感图都已经存在且完成，才允许重新修图。

但本场景中：

- 精修图已经存在，本次需要重新生成，并在成功后覆盖旧精修图。
- 氛围感图从未生成，本次需要创建新的关联图片。

由于氛围感图历史上不存在，接口拒绝了整个请求，导致客户端无法通过一次请求同时完成“覆盖已有精修图”和“新增氛围感图”。

客户端当前请求已经正确传递 `type = 3` 和两个模板 ID，无需修改请求结构。

## 4. 期望接口行为

建议将 `ai-reretouch` 调整为按输出类型分别执行的 **upsert（存在则覆盖，不存在则新增）** 语义。

对于本次请求：

### 原图精修

- 请求传入了 `refined_template_id`。
- 旧精修图已经存在。
- 后端创建新的精修任务。
- 新任务成功后覆盖旧精修图。
- 新任务处理中或失败时保留旧精修图。

### 氛围感修图

- 请求传入了 `atmosphere_template_id`。
- 旧氛围感图不存在。
- 后端创建新的氛围感任务。
- 任务成功后，将结果保存为原图的新关联图片。

### 整体任务

- 一次请求创建两个输出任务：`refined` 和 `atmosphere`。
- 按两个实际创建的输出预占 2 张修图额度。
- 两个输出分别执行、分别记录状态、分别结算额度。
- 单个输出失败不应影响另一个已经成功的输出。

## 5. 建议的后端处理规则

### 5.1 基础校验

建议校验：

- 原图素材存在。
- 原图素材属于指定相册或批次。
- 原图当前状态允许提交 AI 修图任务。
- 请求中至少传入一个与 `type` 匹配的有效模板 ID。
- 用户剩余额度满足本次实际创建的输出数量。

不建议校验：

- `type = 3` 时要求精修和氛围感历史结果都必须存在。
- 某一种关联图从未生成时直接拒绝整个请求。

### 5.2 按模板字段创建任务

后端根据本次实际传入的模板字段创建对应任务：

| 请求情况 | 期望处理 |
| --- | --- |
| 只传 `refined_template_id` | 只创建精修任务 |
| 只传 `atmosphere_template_id` | 只创建氛围感任务 |
| 两个模板 ID 都传 | 同时创建精修和氛围感任务 |
| 某个模板 ID 未传 | 不处理、不覆盖该类型的已有结果 |

### 5.3 按输出类型处理已有结果

对于每个实际提交的输出类型，分别判断：

| 历史状态 | 建议处理 |
| --- | --- |
| 已存在成功结果 | 创建重修任务，新结果成功后替换旧结果 |
| 从未生成 | 创建新任务，成功后新增关联图片 |
| 历史任务失败或已取消 | 允许重新创建任务 |
| 当前已有处理中或排队任务 | 拒绝该类型重复提交，或通过幂等机制复用已有任务 |

### 5.4 替换时机

继续采用现有 `replace_on_success` 语义：

- 新结果成功后，才替换同类型旧结果。
- 新任务排队、处理中或失败时，保留旧结果。
- 精修和氛围感分别替换，互不影响。

## 6. `type` 参数建议语义

保持现有请求类型和接口路径不变：

| `type` | 语义 | 模板规则 |
| ---: | --- | --- |
| `1` | 只处理精修 | 必须传 `refined_template_id`，忽略氛围感模板 |
| `2` | 只处理氛围感 | 必须传 `atmosphere_template_id`，忽略精修模板 |
| `3` | 同时处理精修和氛围感 | 根据实际传入的两个模板分别创建任务 |

对于 `type = 3`：

- 必须传 `refined_template_id`。
- `atmosphere_template_id` 可以选传。
- 传入氛围感模板时创建氛围感任务。
- 未传氛围感模板时，只重修精修图，并保留已有氛围感图。

## 7. 建议处理伪代码

```text
validateOriginalMaterial(request.id)
validateBatch(request.ai_retouch_batch_id)

outputs = []

if request.refined_template_id is not null:
    outputs.add(
        createTask(
            outputType = refined,
            templateId = request.refined_template_id,
            mode = existingRefinedResult ? replace_on_success : create
        )
    )

if request.atmosphere_template_id is not null:
    outputs.add(
        createTask(
            outputType = atmosphere,
            templateId = request.atmosphere_template_id,
            mode = existingAtmosphereResult ? replace_on_success : create
        )
    )

if outputs is empty:
    return invalid_template_error

reserveQuota(outputs.count)
submitTasks(outputs)
```

注意：实际是否存在旧结果，应按照各自的 `output_type` 独立查询，不能用“两个类型都已完成”作为 `type = 3` 的整体前置条件。

## 8. 期望响应

接口成功响应建议继续返回任务批次信息，并明确本次创建的输出类型。例如：

```json
{
  "code": 100000,
  "data": {
    "ai_retouch_batch_id": 61,
    "source_material_id": 702,
    "outputs": [
      {
        "type": "refined",
        "mode": "replace_on_success",
        "status": "queued"
      },
      {
        "type": "atmosphere",
        "mode": "create",
        "status": "queued"
      }
    ],
    "reserved_units": 2
  },
  "msg": "AI修图任务已提交"
}
```

响应结构可沿用现有实现，不强制增加上述字段；关键要求是一次请求能够成功创建两个对应的修图任务。

## 9. 验收用例

### 用例一：只有旧精修图，同时提交两个模板

- 历史状态：精修已完成，氛围感不存在。
- 请求：`type = 3`，同时传精修和氛围感模板。
- 期望：创建两个任务；精修成功后覆盖，氛围感成功后新增。

### 用例二：只有旧氛围感图，同时提交两个模板

- 历史状态：精修不存在，氛围感已完成。
- 请求：`type = 3`，同时传精修和氛围感模板。
- 期望：创建两个任务；精修成功后新增，氛围感成功后覆盖。

### 用例三：两种旧结果都存在

- 历史状态：精修、氛围感都已完成。
- 请求：`type = 3`，同时传两个模板。
- 期望：创建两个任务，分别在成功后覆盖各自旧结果。

### 用例四：原图 Tab 只选择精修模板

- 历史状态：精修、氛围感均可能存在。
- 请求：`type = 3`，只传 `refined_template_id`。
- 期望：只创建精修任务；不处理、不删除、不覆盖旧氛围感图；预占 1 张额度。

### 用例五：精修后 Tab 重新修图

- 请求：`type = 1`，只传 `refined_template_id`。
- 期望：只创建精修任务，新精修成功后覆盖旧精修图。

### 用例六：氛围感 Tab 重新修图

- 请求：`type = 2`，只传 `atmosphere_template_id`。
- 期望：只创建氛围感任务，新氛围感成功后覆盖旧氛围感图。

### 用例七：其中一个输出失败

- 请求创建精修和氛围感两个任务。
- 精修成功，氛围感失败。
- 期望：保留成功的新精修结果；氛围感旧图存在时继续保留旧图，不存在时不生成关联图；额度分别结算。

### 用例八：防止重复提交

- 同一原图、同一输出类型已经存在排队中或处理中的任务。
- 用户再次提交相同任务。
- 期望：通过幂等机制返回原任务，或仅拒绝重复的输出类型，避免重复扣减额度和重复生成结果。

## 10. 总结

希望 `ai-reretouch` 支持以下统一语义：

> 对本次传入模板对应的每种输出独立处理：已有结果则在新任务成功后覆盖，没有结果则新增；未传模板的类型不处理。不要因为某一种关联图历史上从未生成，就拒绝整个重新修图请求。