9.5 KiB
9.5 KiB
AI 修图需求文档
本文档描述旅拍相册中 AI 修图的产品需求和业务规则。后端接口建议见同目录《AI 修图接口文档》。
1. 目标与范围
- 相册管理页面展示用户已在其他流程上传到 OSS、并已在后端登记的图片素材。
- 用户可从网格页批量发起 AI 修图，也可从单图预览页首次修图或重新修图。
- 精修图和氛围感图是某张原图的“关联图”；封面图是相册内的独立素材，不归属于任何一张原图。
- AI 生成为异步长流程，页面必须能分辨已提交、排队、处理、成功和失败。
2. 核心概念
2.1 原图项目
一张原图与它的精修图、氛围感图共同组成一个原图项目。原图的素材 ID 是项目的稳定标识，OSS URL 不作为业务标识。
2.2 关联图
refined：精修图，一张原图最多保留一个当前有效版本。atmosphere：氛围感图，一张原图最多保留一个当前有效版本。- 关联图不作为独立 Cell 出现在相册网格中，只在该原图的预览页 Tab 中展示。
2.3 封面图
- 一次选择不少于 4 张原图时，必须选择封面模板。
- 封面模板使用本次选中的多张原图生成封面图。
- 封面图不关联某张原图，生成成功后作为
cover类型的独立素材出现在相册网格中。 - 删除参与生成封面的原图时，不级联删除已生成的独立封面图。
3. 相册管理页
3.1 网格列表
- 网格展示原图和独立封面图，不直接展示精修图、氛围感图。
- 列表需支持稳定分页。AI 任务执行期间可能插入新的封面素材，不应造成重复或漏项。
- 点击原图 Cell 进入图片预览页，可横向滑动切换其他原图项目。
3.2 Cell 修图状态
Cell 左上角展示稳定的修图状态：
| 状态 | 含义 |
|---|---|
| 已上传 | 原图已登记，从未提交 AI 修图，当前也没有任务 |
| 待处理 | AI 任务已提交，正在排队 |
| 修图中 | AI 任务已开始执行 |
| AI 已修 | 最新任务已成功，存在有效 AI 结果 |
| 失败 | 最新任务执行失败，可能仍保留上一版成功结果 |
状态以后端返回的枚举代码为准，客户端自行映射中文文案，不依赖可变的中文状态名。
3.3 批量 AI 修图
- 用户进入多选模式并选择一张或多张原图。
- 点击底部“AI 修图”，弹出模板选择页。
- 精修模板必选且单选。
- 氛围感模板可选且单选，已选时可取消。
- 选中原图数量小于 4 时不展示封面模板。
- 选中原图数量大于等于 4 时展示封面模板，且必须单选一个。
- 提交后，每张原图分别生成精修图，选了氛围感模板时再分别生成氛围感图。
- 选了封面模板时，整个批次额外生成独立封面图。
- 提交成功指后端已受理任务，不代表图片已生成。
3.4 修图额度
- 模板选择弹窗的底部固定显示当前用户可用的 AI 修图剩余额度，文案例如“剩余 12 次”，不随模板列表滚动消失。
- 精修和氛围感生成会消耗修图额度；封面模板生成不消耗任何修图额度。
- 本需求默认按生成结果张数计费：每张原图的精修结果消耗 1 次，每张原图的氛围感结果消耗 1 次，封面结果消耗 0 次。最终单价由后端返回，客户端不硬编码。
- 重新修图与首次修图使用相同的额度规则。
- 后端受理任务时预占本次所需额度，避免用户并发提交造成超额。
- 只对最终生成成功的精修/氛围感结果扣减额度；失败或取消的子任务释放对应预占额度。
- 如剩余可用额度不足，提交按钮禁用并显示明确提示；后端提交接口仍必须做最终校验。
3.5 批量删除
- 用户多选原图后点击“删除”，删除选中原图及各自的精修图、氛围感图，并取消关联的未完成任务。已有任务记录保留用于审计和排查，但不再对客户端展示已删除素材。
- 已生成的独立封面图不在级联删除范围内，除非用户明确选中该封面素材本身。
- 批量删除应只调用一次后端接口，后端应返回整体或逐项结果，不由客户端循环调用单删接口。
4. 图片预览页
4.1 横向切换
- 从网格点击某张原图进入预览页。
- 横向滑动在相册内的不同原图项目之间切换。
- 切换到新的原图项目时，默认显示其“原图”。
4.2 底部操作
页面底部固定显示三个按钮：
- AI 修图
- 删除
- 刷新
4.3 关联图 Tab
- 如果当前原图没有任何已生成的关联图，不显示 Tab；首次生成任务排队或处理期间仍不显示。
- 存在至少一张已成功的关联图时显示 Tab。
- Tab 最多包含“原图”、“精修后”、“氛围感”；关联图 Tab 只在对应图片已生成时显示。
- 点击 Tab 切换当前原图项目内的展示图片，不切换原图项目。
- 某个已有结果的 Tab 重新提交修图后，仍可展示上一版图片，同时通过该结果槽位的任务状态展示“待处理/修图中/失败”。
- 首次生成尚无图片 URL 时，通过原图 Cell 状态和项目任务状态表达进度，不创建空 Tab。
4.4 预览页删除
- 删除的对象始终是当前原图项目，而不是当前 Tab 上的单张关联图。
- 删除原图及其所有关联图，并取消关联的未完成任务；历史任务记录保留用于审计。
- 删除成功后显示下一个原图项目；如果删除的是末项，则回退上一项；无剩余项时关闭预览页。
4.5 预览页 AI 修图
| 当前情况 | 模板要求 | 生成与覆盖规则 |
|---|---|---|
| 不显示 Tab | 精修必选，氛围感可选 | 首次生成关联的精修图，可选生成氛围感图 |
| 已显示 Tab，当前为“原图” | 精修必选，氛围感可选 | 重新生成精修图；如选氛围感则也重新生成。新结果成功后原子替换对应旧结果 |
| 已显示 Tab，当前为“精修后” | 精修必选 | 只重新生成精修图，成功后覆盖旧精修图，不影响氛围感图 |
| 已显示 Tab，当前为“氛围感” | 氛围感必选 | 只重新生成氛围感图，成功后覆盖旧氛围感图，不影响精修图 |
重新修图期间应保留上一版成功图片可见；只有新结果成功时才原子替换当前版本。失败时继续保留旧版本，并返回可展示的错误信息。
4.6 刷新
- 点击“刷新”只获取当前显示原图项目的最新数据，包括原图、关联图、各结果槽位的任务状态和整体修图状态。
- 不应为刷新一张图重新拉取整个分页列表。
- 服务端对已替换的图片应返回新的资源版本或新 URL，避免 CDN/客户端缓存继续显示旧图。
5. 异步任务规则
- 每次提交返回唯一
job_id、服务端接收时间和当前状态。 - 每次提交同时返回额度预占数、提交前剩余额度和预占后可用额度。
- 任务状态至少包含：
queued、processing、succeeded、partially_succeeded、failed、canceled。 - 精修、氛围感和封面子任务可以独立成功或失败，服务端需保留逐原图、逐结果类型的状态。
- 客户端重试同一次提交时不得创建重复任务，由幂等键保证。
- 同一原图、同一结果类型存在未完成任务时，服务端拒绝再次提交，避免旧任务晚完成后覆盖新结果。
6. 删除与数据一致性
- 删除原图项目需在一个后端业务操作中完成：标记原图删除、标记关联图删除、取消未完成任务。
- 数据库状态成功后再异步清理 OSS 文件，不应因 OSS 删除失败导致客户端删除失败。
- AI 回调必须检查任务和素材是否已删除或已被新版本替代，过期回调不得恢复已删除素材或覆盖新结果。
7. 异常与提示
- 模板加载失败：保留页面并允许重试。
- 模板已下线：提交时返回明确错误码，客户端刷新模板列表。
- 素材不存在、不属于当前相册或不是原图：整次提交不受理，并返回问题素材 ID。
- 数量不满足封面规则：返回稳定错误码和最小数量。
- 任务部分成功：保留已成功结果，失败槽位提供错误码、错误信息和是否可重试。
- 网络超时：客户端使用原幂等键重试，不可产生两个任务。
8. 权限与校验
- 后端必须从登录态校验用户对相册、原图和模板的访问权，不信任客户端传入的用户 ID、景区 ID 或批次 ID。
- 模板是否适用于相册所属景区，由后端根据相册 ID 推导和校验。
- 后端负责校验精修、氛围感和封面模板的必选/可选规则，客户端校验只用于交互提示。
9. 默认产品决策
为使接口和异步覆盖行为可实现，本文档采用以下默认决策：
- 重新修图不先删旧图；新图成功后才原子切换，失败仍保留旧图。
- 在“原图” Tab 重新修图时，若用户未选氛围感模板，保留现有氛围感图，只替换精修图。
- 封面图只在生成成功后插入网格；生成前由所选原图的修图状态和任务详情表达进度。
- 每个关联图类型只对外暴露一个当前有效版本；历史版本是否长期保留属于后端存储策略，不在当前客户端功能中展示。
第 2 条是对“氛围感模板可选”的安全解释：未选不等于删除旧结果。如产品希望未选时删除旧氛围感图，应增加明确的“移除氛围感”操作，不建议让后端根据字段缺失隐式删除。