817 lines
30 KiB
Markdown
817 lines
30 KiB
Markdown
# AI 修图任务中心需求与接口设计
|
||
|
||
> 文档状态：待产品、后端、Android、iOS 联审
|
||
> 更新日期：2026-08-14
|
||
> 适用范围：随心瞰商家版 AI 修图任务，不包含人工修图任务
|
||
|
||
## 1. 背景与目标
|
||
|
||
AI 修图属于异步长耗时任务。当前用户提交后只能等待或主动返回相册刷新，无法明确知道任务是否仍在排队、预计何时完成、哪些照片成功或失败。
|
||
|
||
本需求增加：
|
||
|
||
1. 当前账号全部相册的 AI 修图任务列表。
|
||
2. 单次 AI 修图任务详情。
|
||
3. AI 修图终态消息推送。
|
||
4. 从推送和任务列表进入对应任务的完整导航链路；提交成功后仅 Toast 提示并返回相册管理。
|
||
|
||
本期解决“看得到进度、完成会通知、结果可直达”的问题，不增加任务取消、批量重试、历史版本管理或后台供应商诊断能力。
|
||
|
||
## 2. 核心产品决策
|
||
|
||
### 2.1 推送跳转结论
|
||
|
||
AI 修图推送优先跳转到对应任务详情页。
|
||
|
||
原因：
|
||
|
||
- 用户点击完成通知时，核心意图是确认这一次任务的结果，而不是重新查找任务。
|
||
- 详情页可以直接表达成功、部分成功和失败，减少一次列表定位操作。
|
||
- `ai_retouch_batch_id` 是稳定任务标识，可以支撑前台、后台和冷启动直达。
|
||
|
||
以下情况降级进入任务列表：
|
||
|
||
- 推送缺少 `ai_retouch_batch_id`。
|
||
- ID 类型异常、为 0 或负数。
|
||
- 详情接口返回任务不存在、已失效或当前账号无权访问。
|
||
- 未来客户端收到无法识别的 AI 修图终态数据。
|
||
|
||
### 2.2 推送类型
|
||
|
||
| `type` | 业务含义 | 本需求处理 |
|
||
|---:|---|---|
|
||
| `10` | 人工修图完成通知 | 保持原业务语义和原点击行为，不作复用 |
|
||
| `14` | AI 修图任务通知 | 新增，按 `ai_retouch_batch_id` 进入 AI 修图任务详情 |
|
||
|
||
后端需在 `PushMsg` 类型定义及类型名称映射中增加：
|
||
|
||
```text
|
||
14 => AI修图任务通知
|
||
```
|
||
|
||
### 2.3 任务唯一标识
|
||
|
||
列表、详情、推送和提交响应统一使用已有的 `ai_retouch_batch_id`，类型固定为正整数。不得再引入另一套 `job_id`，避免与素材接口和重新修图接口中的批次标识无法对应。
|
||
|
||
### 2.4 列表范围
|
||
|
||
任务列表展示当前登录账号有权限查看的全部相册任务，不要求用户先进入某个相册。任务卡必须显示所属相册信息。
|
||
|
||
## 3. 用户流程与入口
|
||
|
||
### 3.1 主流程
|
||
|
||
```text
|
||
相册管理选择照片
|
||
→ 提交 AI 修图
|
||
→ 后端返回 ai_retouch_batch_id
|
||
→ 客户端 Toast 提示“AI修图任务已提交，完成后将通过消息通知”
|
||
→ 关闭模板页及可能存在的照片预览页，回到相册管理并刷新列表
|
||
→ 用户可离开页面
|
||
→ 任务进入终态后收到 type = 14 推送
|
||
→ 点击推送进入任务详情
|
||
→ 查看成功结果或进入相册处理失败项
|
||
```
|
||
|
||
### 3.2 页面入口
|
||
|
||
- 相册管理页导航栏右侧增加“修图任务”，进入当前账号的全局任务列表；新增相册页不展示该入口。
|
||
- AI 修图提交成功仅展示自动消失的 Toast，不弹出查看任务确认框，也不提供立即跳转操作。
|
||
- 提交成功后回到相册管理页，并刷新相册摘要、数量和当前素材列表。
|
||
- 任务列表点击卡片进入对应任务详情。
|
||
- `type = 14` 推送携带有效任务 ID 时直达详情，否则进入任务列表。
|
||
|
||
## 4. 任务状态定义
|
||
|
||
后端状态值必须稳定，客户端根据枚举映射中文，不依赖后端返回的中文状态名。
|
||
|
||
| 状态 | 是否终态 | 列表分组 | 中文展示 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `queued` | 否 | 进行中 | 排队中 | 已受理，尚无子任务开始 |
|
||
| `processing` | 否 | 进行中 | 修图中 | 至少一个子任务开始，尚未全部结束 |
|
||
| `succeeded` | 是 | 已完成 | 已完成 | 所有子任务成功 |
|
||
| `partially_succeeded` | 是 | 已完成 | 部分完成 | 子任务全部结束，既有成功也有失败或取消 |
|
||
| `failed` | 是 | 失败 | 处理失败 | 子任务全部结束，没有成功结果 |
|
||
| `canceled` | 是 | 失败 | 已取消 | 任务因素材删除或后台操作被取消 |
|
||
|
||
进度必须满足：
|
||
|
||
```text
|
||
total = queued + processing + succeeded + failed + canceled
|
||
completed = succeeded + failed + canceled
|
||
```
|
||
|
||
客户端进度百分比只能通过 `completed / total` 计算；`total <= 0` 时隐藏进度百分比，不显示虚构进度。
|
||
|
||
## 5. 任务列表页
|
||
|
||
### 5.1 设计稿
|
||
|
||
|
||
|
||
### 5.2 页面结构
|
||
|
||
1. 导航栏
|
||
- 返回按钮。
|
||
- 标题“AI修图任务”。
|
||
2. 状态筛选
|
||
- 全部。
|
||
- 进行中。
|
||
- 已完成。
|
||
- 失败。
|
||
3. 任务卡列表
|
||
- 所属相册名称。
|
||
- 用户脱敏手机号。
|
||
- 提交时间。
|
||
- 任务编号，例如“任务 #9521”。
|
||
- 1 至 3 张原图缩略图；多余图片通过数量表达，不继续横向堆叠。
|
||
- 输出摘要，例如“精修 4 张 · 氛围感 4 张 · 封面 1 张”。
|
||
- 状态图标与文字标签。
|
||
- 进度或终态结果摘要。
|
||
- 详情指示。
|
||
|
||
### 5.3 状态展示
|
||
|
||
| 状态 | 卡片主信息 | 辅助信息 |
|
||
|---|---|---|
|
||
| `queued` | 排队中 | 有 ETA 时显示预计完成时间，否则显示“完成后将通过消息通知” |
|
||
| `processing` | 已完成 N / M | 显示进度条与预计完成时间 |
|
||
| `succeeded` | N 张结果已生成 | 显示完成时间 |
|
||
| `partially_succeeded` | N 张成功 · M 张失败 | 使用橙色警示，不按整单失败展示 |
|
||
| `failed` | 处理失败 | 引导点击查看详情 |
|
||
| `canceled` | 已取消 | 显示取消时间；不展示供应商或内部日志 |
|
||
|
||
### 5.4 失败信息展示
|
||
|
||
- 列表只承担任务级概览，不逐张展开失败原因。
|
||
- `partially_succeeded` 使用“N 张成功 · M 张失败”作为唯一结果摘要；`failed` 使用“失败”，不再增加独立的失败摘要行。
|
||
- 列表卡整体可点击并保留“查看详情”指示，具体失败原因统一进入详情查看，避免与结果数量重复。
|
||
- 后端返回的 `failure_summary` 继续解析并保留，供通知、无逐项错误数据等降级场景使用；列表首版不直接展示。
|
||
- 详情里的逐照片 `error.message` 仍是用户查看失败原因的主要信息来源，不展示原始错误码。
|
||
|
||
### 5.5 刷新与分页
|
||
|
||
- 首次进入、下拉刷新和 App 回到前台时拉取第一页。
|
||
- 页面可见且存在 `queued` 或 `processing` 任务时，每 15 秒刷新第一页。
|
||
- 页面离开、App 进入后台或页面内所有任务终态后停止定时刷新。
|
||
- 加载更多使用不透明游标；客户端不得解析或拼接游标。
|
||
- 服务端排序固定为 `created_at DESC, ai_retouch_batch_id DESC`，避免同一时间创建的任务分页不稳定。
|
||
- 刷新第一页时按 `ai_retouch_batch_id` 合并，不能产生重复卡片。
|
||
|
||
### 5.6 空态和异常
|
||
|
||
| 场景 | 展示 |
|
||
|---|---|
|
||
| 账号从未提交任务 | “暂无AI修图任务”与“提交修图后可在这里查看进度” |
|
||
| 当前筛选无数据 | “暂无该状态的任务” |
|
||
| 首屏加载失败 | 错误说明和“重新加载” |
|
||
| 加载更多失败 | 保留现有列表，底部提供重试 |
|
||
|
||
## 6. 任务详情页
|
||
|
||
### 6.1 设计稿
|
||
|
||
|
||
|
||
### 6.2 页面结构
|
||
|
||
1. 导航栏
|
||
- 返回按钮。
|
||
- 标题“任务详情”。
|
||
- 手动刷新按钮。
|
||
2. 状态摘要卡
|
||
- 任务状态图标和文字。
|
||
- 完成数量与进度条。
|
||
- 预计完成时间或实际完成时间。
|
||
- 非终态展示“完成后将通过消息通知你”。
|
||
3. 相册与任务信息
|
||
- 相册封面、相册名称、脱敏手机号。
|
||
- 任务编号、提交时间、开始时间、完成时间或处理耗时。
|
||
4. 任务内容
|
||
- 精修、氛围感、封面的目标数量。
|
||
- 额度预占、实际消耗和释放数量。
|
||
5. 处理明细
|
||
- 按原图组织精修和氛围感子任务。
|
||
- 封面作为独立明细。
|
||
- 每项展示照片缩略图、文件名、模板名称和状态。
|
||
- 某个输出失败时，在该照片、该输出项内部紧邻状态展示后端失败原因。
|
||
6. 页面操作
|
||
- 成功结果：“查看结果”，进入照片预览对应 Tab。
|
||
- 失败结果：仅展示后端返回的用户可理解失败原因，不在失败原因后追加操作按钮。
|
||
- 页面底部始终可提供“查看相册”。
|
||
|
||
### 6.3 失败原因展示
|
||
|
||
失败原因必须和失败照片、失败输出类型绑定展示，不使用全局弹窗、Toast 或脱离上下文的页面顶部提示代替。
|
||
|
||
| 场景 | 展示规则 |
|
||
|---|---|
|
||
| 单个精修/氛围感失败 | 在对应输出项状态“生成失败”下方显示“失败原因：{error.message}” |
|
||
| 同一照片两种输出均失败 | 精修、氛围感分别显示各自原因，不合并为一个模糊原因 |
|
||
| 封面失败 | 在封面独立明细下方显示原因 |
|
||
| 任务仍在处理中但已有失败项 | 立即展示已确定的照片失败原因，不等整批任务终态 |
|
||
| 后端原因为空 | 展示客户端兜底“处理失败，请稍后重试” |
|
||
| 原因超过两行 | 默认显示两行并提供“查看完整原因”；辅助功能朗读完整文本 |
|
||
|
||
视觉规则：
|
||
|
||
- 使用红色错误图标、红色“生成失败”和淡红色原因容器；颜色不是唯一状态提示。
|
||
- `error.message` 使用正文级字号和足够对比度，不使用脚注小字弱化重要信息。
|
||
- 不展示 `error.code`、供应商名称、堆栈、请求 ID 或服务器路径。
|
||
- 无论 `retryable` 取值如何，失败原因区域均只展示原因；用户仍可通过详情页底部“查看相册”进入相册管理页。
|
||
- 用户返回页面或手动刷新后，失败原因随接口最新值更新。
|
||
|
||
### 6.4 刷新规则
|
||
|
||
- 详情首次出现时立即请求最新数据。
|
||
- 非终态且页面可见时每 8 秒刷新。
|
||
- 进入终态、页面离开或 App 进入后台时停止刷新。
|
||
- 手动刷新与定时刷新不能并发发起重复请求。
|
||
- 推送不作为唯一状态来源；用户关闭通知权限后仍可通过页面刷新获得终态。
|
||
|
||
### 6.5 查看结果规则
|
||
|
||
- `output_type = refined`：打开来源原图的照片预览，默认选中“精修后”。
|
||
- `output_type = atmosphere`：打开来源原图的照片预览，默认选中“氛围感”。
|
||
- `output_type = cover`：打开所属相册，并定位到生成的封面素材；无法定位时进入相册第一页。
|
||
- 结果资源已删除或不可用时，隐藏“查看结果”并展示“结果已失效”。
|
||
|
||
## 7. 视觉与可访问性规范
|
||
|
||
### 7.1 视觉 Token
|
||
|
||
| 用途 | 建议值 |
|
||
|---|---|
|
||
| 页面背景 | `#F5F7FB` |
|
||
| 卡片背景 | `#FFFFFF` |
|
||
| 品牌主色 | `#1677FF` |
|
||
| 蓝色高光 | `#3A91FF` |
|
||
| 主文字 | `#111827` |
|
||
| 次文字 | `#64748B` |
|
||
| 成功 | `#22A06B` |
|
||
| 警示/部分完成 | `#F59E0B` |
|
||
| 失败 | `#EF4444` |
|
||
| 卡片圆角 | 12–16 pt |
|
||
|
||
### 7.2 交互要求
|
||
|
||
- 状态必须同时使用图标、文字和颜色，不得只用颜色区分。
|
||
- 正文文字与背景对比度至少 4.5:1。
|
||
- 卡片、筛选项和操作按钮的最小触控区域为 44 × 44 pt。
|
||
- 动态字体至少覆盖系统默认至辅助功能常用档位；文字放大时允许卡片增高。
|
||
- 进度动画尊重“减弱动态效果”；关闭动画后保留静态进度与文字。
|
||
- 网络图片使用缩略图地址，并提供占位图和失败占位状态。
|
||
|
||
## 8. 后端接口总览
|
||
|
||
基础路径：
|
||
|
||
```text
|
||
/api/yf-handset-app/photog/travel-album
|
||
```
|
||
|
||
| 方法 | 路径 | 类型 | 用途 |
|
||
|---|---|---|---|
|
||
| `POST` | `/ai-retouch` | 扩展现有响应 | 首次/批量提交后返回任务标识 |
|
||
| `POST` | `/ai-reretouch` | 扩展现有响应 | 重新修图提交后返回任务标识 |
|
||
| `GET` | `/ai-retouch-job-list` | 新增 | 获取当前账号全部 AI 修图任务 |
|
||
| `GET` | `/ai-retouch-job-info` | 实现并统一 | 获取指定任务详情 |
|
||
|
||
时间字段统一使用 ISO 8601 UTC，例如：
|
||
|
||
```text
|
||
2026-08-14T06:26:12.123Z
|
||
```
|
||
|
||
所有 ID 的 JSON 类型必须稳定；本需求中的 `ai_retouch_batch_id`、`user_equity_travel_id` 和素材 ID 均使用整数。
|
||
|
||
## 9. 扩展 AI 修图提交响应
|
||
|
||
现有 `/ai-retouch` 和 `/ai-reretouch` 请求体保持不变，成功后统一返回可供跳转和立即展示的任务摘要。
|
||
|
||
HTTP 状态码：`202 Accepted`
|
||
|
||
```json
|
||
{
|
||
"code": 100000,
|
||
"msg": "AI修图任务已提交",
|
||
"data": {
|
||
"ai_retouch_batch_id": 9521,
|
||
"user_equity_travel_id": 88,
|
||
"status": "queued",
|
||
"progress": {
|
||
"total": 9,
|
||
"queued": 9,
|
||
"processing": 0,
|
||
"succeeded": 0,
|
||
"failed": 0,
|
||
"canceled": 0
|
||
},
|
||
"created_at": "2026-08-14T06:26:12.123Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
必有字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `ai_retouch_batch_id` | int | 大于 0 的任务唯一标识 |
|
||
| `user_equity_travel_id` | int | 所属相册 ID |
|
||
| `status` | string | 提交成功时通常为 `queued` |
|
||
| `progress` | object | 提交时的真实子任务数量 |
|
||
| `created_at` | string | 服务端受理时间 |
|
||
|
||
客户端超时后使用原幂等键重试时，后端必须返回同一个 `ai_retouch_batch_id`，不得创建重复任务。
|
||
|
||
## 10. 获取 AI 修图任务列表
|
||
|
||
### 10.1 请求
|
||
|
||
```http
|
||
GET /api/yf-handset-app/photog/travel-album/ai-retouch-job-list?status_group=in_progress&limit=20&cursor=<opaque_cursor>
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
| 参数 | 必填 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `status_group` | 否 | string | `all` | `all`、`in_progress`、`completed`、`failed` |
|
||
| `limit` | 否 | int | `20` | 最小 1，最大 50 |
|
||
| `cursor` | 否 | string | — | 服务端返回的不透明游标，第一页不传 |
|
||
|
||
服务端分组映射：
|
||
|
||
| `status_group` | 包含状态 |
|
||
|---|---|
|
||
| `all` | 全部六种状态 |
|
||
| `in_progress` | `queued`、`processing` |
|
||
| `completed` | `succeeded`、`partially_succeeded` |
|
||
| `failed` | `failed`、`canceled` |
|
||
|
||
### 10.2 响应
|
||
|
||
```json
|
||
{
|
||
"code": 100000,
|
||
"msg": "success",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"ai_retouch_batch_id": 9521,
|
||
"user_equity_travel_id": 88,
|
||
"scope": "batch",
|
||
"status": "processing",
|
||
"album": {
|
||
"id": 88,
|
||
"name": "旅拍相册",
|
||
"user_phone": "13812348000",
|
||
"cover_url": "https://cdn.example.com/albums/88/cover.jpg"
|
||
},
|
||
"source_count": 4,
|
||
"outputs": [
|
||
{
|
||
"type": "refined",
|
||
"count": 4
|
||
},
|
||
{
|
||
"type": "atmosphere",
|
||
"count": 4
|
||
},
|
||
{
|
||
"type": "cover",
|
||
"count": 1
|
||
}
|
||
],
|
||
"preview_images": [
|
||
{
|
||
"material_id": 2031,
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2031_thumb.jpg"
|
||
},
|
||
{
|
||
"material_id": 2032,
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2032_thumb.jpg"
|
||
},
|
||
{
|
||
"material_id": 2033,
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2033_thumb.jpg"
|
||
}
|
||
],
|
||
"progress": {
|
||
"total": 9,
|
||
"queued": 3,
|
||
"processing": 1,
|
||
"succeeded": 5,
|
||
"failed": 0,
|
||
"canceled": 0
|
||
},
|
||
"estimated_finish_at": "2026-08-14T06:32:00.000Z",
|
||
"failure_summary": null,
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": "2026-08-14T06:26:18.000Z",
|
||
"finished_at": null
|
||
}
|
||
],
|
||
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0xNFQwNjoyNjoxMi4xMjNaIiwiaWQiOjk1MjF9",
|
||
"has_more": true
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.3 列表字段约定
|
||
|
||
| 字段 | 必有 | 说明 |
|
||
|---|---|---|
|
||
| `album` | 是 | 服务端按登录态校验后返回，客户端不再逐任务查询相册 |
|
||
| `album.user_phone` | 否 | 返回原始手机号时客户端脱敏；没有时返回空字符串，不返回多种类型 |
|
||
| `outputs` | 是 | 各输出类型的计划生成数量 |
|
||
| `preview_images` | 是 | 最多返回 3 项，允许为空数组 |
|
||
| `progress` | 是 | 六种子任务数量必须满足进度恒等式 |
|
||
| `estimated_finish_at` | 否 | 无法估算或已终态时返回 `null` |
|
||
| `failure_summary` | 否 | 任务级可展示摘要；`failed` 时必有，其他状态存在失败子任务时建议返回 |
|
||
| `next_cursor` | 是 | 无下一页时为 `null` |
|
||
| `has_more` | 是 | 与 `next_cursor` 语义一致 |
|
||
|
||
`estimated_finish_at` 是动态估算而非 SLA。估算变化时允许更新；客户端只展示最新值，不做倒计时承诺。
|
||
|
||
`failure_summary` 不代替逐照片失败原因。存在多个不同失败原因时，列表建议返回“N 张照片处理失败，点击查看原因”；只有单一且简短的原因时才直接返回该原因。建议限制在 60 个中文字符以内。
|
||
|
||
## 11. 获取 AI 修图任务详情
|
||
|
||
### 11.1 请求
|
||
|
||
```http
|
||
GET /api/yf-handset-app/photog/travel-album/ai-retouch-job-info?ai_retouch_batch_id=9521
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
| 参数 | 必填 | 类型 | 说明 |
|
||
|---|---|---|---|
|
||
| `ai_retouch_batch_id` | 是 | int | 大于 0 的 AI 修图批次 ID |
|
||
|
||
接口不要求客户端再传 `user_equity_travel_id`。后端应从登录态和任务归属完成权限校验，并在响应中返回相册信息。
|
||
|
||
### 11.2 响应
|
||
|
||
```json
|
||
{
|
||
"code": 100000,
|
||
"msg": "success",
|
||
"data": {
|
||
"ai_retouch_batch_id": 9521,
|
||
"user_equity_travel_id": 88,
|
||
"scope": "batch",
|
||
"status": "processing",
|
||
"album": {
|
||
"id": 88,
|
||
"name": "旅拍相册",
|
||
"user_phone": "13812348000",
|
||
"cover_url": "https://cdn.example.com/albums/88/cover.jpg"
|
||
},
|
||
"source_count": 4,
|
||
"outputs": [
|
||
{
|
||
"type": "refined",
|
||
"count": 4
|
||
},
|
||
{
|
||
"type": "atmosphere",
|
||
"count": 4
|
||
},
|
||
{
|
||
"type": "cover",
|
||
"count": 1
|
||
}
|
||
],
|
||
"progress": {
|
||
"total": 9,
|
||
"queued": 2,
|
||
"processing": 1,
|
||
"succeeded": 5,
|
||
"failed": 1,
|
||
"canceled": 0
|
||
},
|
||
"quota_settlement": {
|
||
"status": "partially_settled",
|
||
"reserved_units": 8,
|
||
"consumed_units": 5,
|
||
"released_units": 1,
|
||
"cover_units": 0
|
||
},
|
||
"targets": [
|
||
{
|
||
"target_id": 30101,
|
||
"source_material": {
|
||
"id": 2031,
|
||
"file_name": "IMG_8291.JPG",
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2031_thumb.jpg"
|
||
},
|
||
"input_material_ids": [2031],
|
||
"output_type": "refined",
|
||
"template": {
|
||
"id": 11,
|
||
"name": "自然通透"
|
||
},
|
||
"status": "succeeded",
|
||
"result_asset": {
|
||
"id": 9201,
|
||
"material_id": 2031,
|
||
"url": "https://cdn.example.com/albums/88/2031_refined_v2.jpg",
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2031_refined_v2_thumb.jpg"
|
||
},
|
||
"error": null,
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": "2026-08-14T06:26:18.000Z",
|
||
"finished_at": "2026-08-14T06:28:40.000Z"
|
||
},
|
||
{
|
||
"target_id": 30102,
|
||
"source_material": {
|
||
"id": 2032,
|
||
"file_name": "IMG_8292.JPG",
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2032_thumb.jpg"
|
||
},
|
||
"input_material_ids": [2032],
|
||
"output_type": "atmosphere",
|
||
"template": {
|
||
"id": 21,
|
||
"name": "暖阳氛围"
|
||
},
|
||
"status": "processing",
|
||
"result_asset": null,
|
||
"error": null,
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": "2026-08-14T06:29:02.000Z",
|
||
"finished_at": null
|
||
},
|
||
{
|
||
"target_id": 30103,
|
||
"source_material": {
|
||
"id": 2033,
|
||
"file_name": "IMG_8293.JPG",
|
||
"thumbnail_url": "https://cdn.example.com/albums/88/2033_thumb.jpg"
|
||
},
|
||
"input_material_ids": [2033],
|
||
"output_type": "refined",
|
||
"template": {
|
||
"id": 11,
|
||
"name": "自然通透"
|
||
},
|
||
"status": "failed",
|
||
"result_asset": null,
|
||
"error": {
|
||
"code": "AI_PROVIDER_TIMEOUT",
|
||
"message": "AI服务处理超时，请重新修图",
|
||
"retryable": true
|
||
},
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": "2026-08-14T06:27:10.000Z",
|
||
"finished_at": "2026-08-14T06:29:30.000Z"
|
||
},
|
||
{
|
||
"target_id": 30109,
|
||
"source_material": null,
|
||
"input_material_ids": [2031, 2032, 2033, 2034],
|
||
"output_type": "cover",
|
||
"template": {
|
||
"id": 31,
|
||
"name": "旅拍拼贴"
|
||
},
|
||
"status": "queued",
|
||
"result_asset": null,
|
||
"error": null,
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": null,
|
||
"finished_at": null
|
||
}
|
||
],
|
||
"estimated_finish_at": "2026-08-14T06:32:00.000Z",
|
||
"created_at": "2026-08-14T06:26:12.123Z",
|
||
"started_at": "2026-08-14T06:26:18.000Z",
|
||
"finished_at": null,
|
||
"duration_seconds": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11.3 失败明细
|
||
|
||
失败子任务的 `error` 结构：
|
||
|
||
```json
|
||
{
|
||
"code": "AI_PROVIDER_TIMEOUT",
|
||
"message": "AI服务处理超时，请重新修图",
|
||
"retryable": true
|
||
}
|
||
```
|
||
|
||
约定：
|
||
|
||
- `status = failed` 时 `error` 和非空 `error.message` 必须返回，不能只返回错误码。
|
||
- `message` 必须是经过后端转换、可直接展示给用户的中文文案，建议不超过 120 个中文字符。
|
||
- `code` 用于客户端判断与联调排查，不直接展示。
|
||
- 不得返回供应商密钥、内部请求、堆栈、服务器路径或原始异常。
|
||
- `retryable` 只表达业务上是否允许重新提交，本期详情页不直接发起批量重试。
|
||
- `queued`、`processing`、`succeeded` 时 `error` 固定返回 `null`，不要返回空对象。
|
||
- 同一来源照片的精修和氛围感必须分别返回自己的 `error`，客户端不通过素材级公共错误猜测具体失败输出。
|
||
|
||
### 11.4 额度结算
|
||
|
||
| 状态 | 说明 |
|
||
|---|---|
|
||
| `reserved` | 已预占，尚无子任务完成 |
|
||
| `partially_settled` | 部分预占已转为消耗或释放 |
|
||
| `settled` | 所有额度完成结算 |
|
||
|
||
必须满足：
|
||
|
||
```text
|
||
reserved_units >= consumed_units + released_units
|
||
```
|
||
|
||
终态时应满足：
|
||
|
||
```text
|
||
reserved_units = consumed_units + released_units
|
||
```
|
||
|
||
封面不消耗额度，`cover_units` 固定为 0。
|
||
|
||
## 12. 接口错误码
|
||
|
||
| HTTP | 业务码 | 场景 | 客户端行为 |
|
||
|---:|---|---|---|
|
||
| 400 | `INVALID_RETOUCH_STATUS_GROUP` | 列表筛选参数错误 | 回退“全部”并记录联调日志 |
|
||
| 400 | `INVALID_CURSOR` | 游标无效或过期 | 清空游标并重新加载第一页 |
|
||
| 400 | `INVALID_RETOUCH_BATCH_ID` | 任务 ID 非法 | 进入任务列表 |
|
||
| 401 | `UNAUTHORIZED` | 登录态失效 | 走现有重新登录流程，登录后继续待处理路由 |
|
||
| 404 | `AI_RETOUCH_JOB_NOT_FOUND` | 不存在、已失效或无权访问 | 提示“任务不存在或已失效”，进入任务列表 |
|
||
| 429 | `TOO_MANY_REQUESTS` | 刷新过于频繁 | 停止本轮轮询，按服务端建议时间重试 |
|
||
| 500 | `AI_RETOUCH_JOB_QUERY_FAILED` | 服务端异常 | 保留已有数据并提供重试 |
|
||
|
||
权限不足建议统一返回 404，避免泄露其他账号任务是否存在。
|
||
|
||
## 13. AI 修图推送协议
|
||
|
||
### 13.1 发送条件
|
||
|
||
- 只在任务第一次从非终态进入 `succeeded`、`partially_succeeded` 或 `failed` 时发送。
|
||
- `canceled` 默认不发送通知。
|
||
- 同一 `ai_retouch_batch_id` 只发送一次终态推送。
|
||
- 后端应通过事务字段或唯一记录保证幂等，例如 `terminal_push_sent_at`。
|
||
- 设备没有有效极光 Registration ID 时不影响任务结算；用户仍可在任务中心查看结果。
|
||
|
||
### 13.2 统一业务结构
|
||
|
||
```json
|
||
{
|
||
"title": "AI修图已完成",
|
||
"content": "「旅拍相册」的9张结果已生成，点击查看。",
|
||
"msg_id": 2014,
|
||
"type": 14,
|
||
"data": {
|
||
"ai_retouch_batch_id": 9521,
|
||
"user_equity_travel_id": 88,
|
||
"status": "succeeded"
|
||
}
|
||
}
|
||
```
|
||
|
||
字段约定：
|
||
|
||
| 字段 | 必有 | 类型 | 说明 |
|
||
|---|---|---|---|
|
||
| `type` | 是 | int | 固定为 `14` |
|
||
| `msg_id` | 是 | int | 后端业务消息 ID，不是极光 `_j_msgid` |
|
||
| `data` | 是 | object | 不得发送为 JSON 字符串 |
|
||
| `ai_retouch_batch_id` | 是 | int | 大于 0；点击详情的主键 |
|
||
| `user_equity_travel_id` | 是 | int | 用于降级列表和联调排查 |
|
||
| `status` | 是 | string | 仅允许三个会推送的终态值 |
|
||
|
||
### 13.3 通知文案
|
||
|
||
| 状态 | 标题 | 正文模板 |
|
||
|---|---|---|
|
||
| `succeeded` | AI修图已完成 | `「{相册名}」的{成功数}张结果已生成，点击查看。` |
|
||
| `partially_succeeded` | AI修图部分完成 | `{成功数}张成功，{失败数}张失败，点击查看详情。` |
|
||
| `failed` | AI修图未完成 | `本次任务处理失败，点击查看原因。` |
|
||
|
||
相册名称为空时，正文使用“本次AI修图任务”，不得出现空书名号。
|
||
|
||
### 13.4 iOS 示例
|
||
|
||
```json
|
||
{
|
||
"aps": {
|
||
"alert": {
|
||
"title": "AI修图已完成",
|
||
"body": "「旅拍相册」的9张结果已生成，点击查看。"
|
||
},
|
||
"sound": "default"
|
||
},
|
||
"msg_id": 2014,
|
||
"type": 14,
|
||
"data": {
|
||
"ai_retouch_batch_id": 9521,
|
||
"user_equity_travel_id": 88,
|
||
"status": "succeeded"
|
||
}
|
||
}
|
||
```
|
||
|
||
Android 的 `extras` 中放入同一业务对象；字段名、字段类型和业务含义必须与 iOS 一致。
|
||
|
||
## 14. 推送点击路由
|
||
|
||
### 14.1 路由规则
|
||
|
||
```text
|
||
收到通知点击
|
||
→ 解析业务 type
|
||
→ type != 14：继续走现有类型路由
|
||
→ type = 14：解析 data.ai_retouch_batch_id
|
||
→ 合法：打开 AI 修图任务详情
|
||
→ 缺失/非法：打开 AI 修图任务列表
|
||
→ 详情请求 404：提示后返回任务列表
|
||
```
|
||
|
||
### 14.2 生命周期
|
||
|
||
- 前台、后台点击和冷启动使用同一套 `type + data` 解析规则。
|
||
- 未登录时暂存 `ai_retouch_batch_id`，登录成功且主 Tab 建立后继续路由。
|
||
- 账号切换或退出登录时清除上一账号尚未执行的待处理路由。
|
||
- 同一系统通知的 request identifier 只处理一次。
|
||
- 客户端不得从标题或正文解析任务 ID。
|
||
|
||
### 14.3 向后兼容
|
||
|
||
- 旧客户端无法识别 `type = 14` 时按既有默认逻辑进入消息中心，不应崩溃。
|
||
- 新客户端收到 `type = 10` 时仍按人工修图处理，不进入 AI 修图任务中心。
|
||
- 对 `data` 中新增的未知字段，客户端应忽略。
|
||
|
||
### 14.4 站内消息详情入口
|
||
|
||
- `type = 14` 的站内消息详情页在消息正文下方展示品牌蓝主按钮“查看任务详情”。
|
||
- 消息 `extra_data.ai_retouch_batch_id` 合法时进入对应任务详情；兼容 `extra_data.data.ai_retouch_batch_id` 包装结构。
|
||
- 任务 ID 缺失、无法解析或小于等于 0 时，按钮仍保留，点击后降级进入 AI 修图任务列表。
|
||
- `type = 10` 人工修图及其他类型消息不展示该入口，原有消息详情行为保持不变。
|
||
- 底部“删除并返回”继续作为独立的破坏性操作，不承担业务跳转职责。
|
||
|
||
## 15. 数据、安全与一致性
|
||
|
||
- 列表和详情只能返回当前登录账号有权限查看的任务。
|
||
- 后端从登录态确定账号范围，不接受客户端传入用户 ID 扩大查询范围。
|
||
- 手机号仅用于业务识别，客户端统一脱敏展示。
|
||
- 缩略图和结果 URL 应使用受控 CDN 地址；如需签名，过期时间应覆盖合理浏览时长。
|
||
- 任务状态和所有子任务状态必须在同一份一致性快照中返回。
|
||
- 推送发送失败不得回滚已完成的 AI 任务或额度结算。
|
||
- 已删除且不再允许客户端展示的素材，不应继续通过任务详情暴露原图或结果 URL。
|
||
- 如果任务已整体不可见，详情统一返回 `AI_RETOUCH_JOB_NOT_FOUND`。
|
||
|
||
## 16. 验收标准
|
||
|
||
### 16.1 页面
|
||
|
||
- 能从相册管理页进入当前账号全部 AI 修图任务列表，新增相册页不展示该入口。
|
||
- 四种筛选与六种状态映射正确。
|
||
- 进行中任务显示真实完成数量；有 ETA 才显示预计完成时间。
|
||
- 详情可展示任务摘要、相册信息、额度和逐输出明细。
|
||
- 单照片、单输出失败时，失败原因展示在对应明细内部，不需要用户从任务级摘要猜测失败对象。
|
||
- 后端原因超过两行时可查看完整内容；原因缺失时有稳定兜底文案。
|
||
- 成功结果可进入对应照片结果，失败项可进入所属相册。
|
||
- 页面离开或任务终态后停止轮询。
|
||
|
||
### 16.2 接口
|
||
|
||
- 两个提交接口返回稳定且可跳转的 `ai_retouch_batch_id`。
|
||
- 游标分页在任务新增和状态更新期间不重复、不漏项。
|
||
- 进度数量满足恒等式，任务终态与子任务状态一致。
|
||
- ETA 缺失时返回 `null`，不返回空字符串或 0 时间。
|
||
- `status = failed` 的子任务必有非空 `error.message`，且详情能够按照片和输出类型准确展示。
|
||
- 失败信息不包含供应商、堆栈、服务器路径等内部实现。
|
||
|
||
### 16.3 推送
|
||
|
||
- `type = 14` 未被其他业务占用，后端类型名称映射完整。
|
||
- `type = 10` 人工修图和 `type = 14` AI 修图互不影响。
|
||
- 成功、部分成功、失败各只发送一次终态通知。
|
||
- 前台、后台、冷启动、未登录和重复点击均符合路由规则。
|
||
- 缺少任务 ID、非法 ID、任务失效时均安全降级到任务列表。
|
||
|
||
## 17. 本期不做
|
||
|
||
- 从任务中心取消 AI 修图任务。
|
||
- 一键批量重试失败子任务。
|
||
- 展示 AI 供应商、内部错误堆栈或链路日志。
|
||
- 展示同一照片的历史修图版本。
|
||
- 为 ETA 提供 SLA 倒计时承诺。
|
||
- 修改 `type = 10` 人工修图协议。
|
||
|
||
## 18. 设计稿生成说明
|
||
|
||
两张设计稿使用内置 ImageGen 生成，参考现有 AI 修图 V2 的浅色相册管理页面、旅行摄影素材和状态视觉语言。
|
||
|
||
- 任务列表：853 × 1844，展示进行中、已完成、部分完成三种代表性卡片。
|
||
- 任务详情 V2：852 × 1846，展示处理中的任务、6/9 进度、ETA、消息通知说明，以及单照片“生成失败 + 失败原因”的内联状态。
|
||
- 设计稿用于产品和研发对齐；实际 UIKit 实现应使用项目内颜色、字体、SnapKit 和 SF Symbols，不把设计稿作为页面背景切图。
|