suixinkan_uikit/suixinkan/Features/TravelAlbum/AI自动修图后端接口改造精简版.md

AI 自动修图后端接口改造（精简版）

一、需要修改的接口

1. 创建相册

POST /api/yf-handset-app/photog/travel-album/create

请求新增：

{
  "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

每个相册新增响应字段：

{
  "auto_retouch_config": {
    "enabled": true,
    "refined_template_id": 12
  }
}

规则：

• 历史相册没有配置时按关闭状态返回。

二、需要新增的接口

更新相册自动修图配置

POST /api/yf-handset-app/photog/travel-album/auto-retouch-config

请求：

{
  "user_equity_travel_id": 88,
  "enabled": true,
  "refined_template_id": 12
}

成功响应 data：

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