7.4 KiB
7.4 KiB
图片类生成任务：换皮应用通用流程
本文描述「用户图 + 模板生成图片/视频类任务」在换皮应用中的通用产品与技术流程：选图方式、选图后界面表现、上传与创建任务的数据链路、以及上传后与进度相关的界面跳转。具体接口字段、加解密与换皮命名以各应用的配置与《客户端指南》为准；本文不绑定某一仓库内的源码路径。
1. 流程总览
典型端到端路径可以概括为：
- 选图：用户从相机或系统相册取得一张或多张本地图片（依业务是否支持双图等）。
- 选图后界面：展示预览、可选编辑/压缩提示、确认或重选；进入上传前可展示加载或禁用重复提交。
- 上传与创建任务：先拿到服务端下发的预签名上传地址，客户端直传对象存储，再用服务端返回的文件路径调用创建任务，得到
taskId。 - 进度与结果：对
taskId轮询进度，直到成功、失败或超时；界面随状态切换（结果页、重试、返回列表等）。 - 历史：任务列表拉取远端记录，必要时与本地封面缓存合并展示。
与「仅文案、无用户图」的文生图相比，主路径多了「本地文件 → 预签名上传 → 创建任务」这一段；创建成功之后的进度与列表逻辑通常一致。
2. 选图方式：相机与相册
| 方式 | 常见行为 | 产品注意点 |
|---|---|---|
| 相册 | 调起系统图片选择器，用户勾选一张或按业务限制多张 | 需处理权限拒绝、无可用图片、超大图；可在此步限制格式（如仅图片） |
| 相机 | 调起系统相机，拍摄后得到临时文件或相册引用 | 需处理权限、取消拍摄、低内存；部分系统会先落相册再选 |
换皮应用应在交互上明确：当前是「拍一张」还是「从相册选」，避免用户混淆；若业务只允许单图，应在选图结果回调里统一成单文件路径再进入下一步。
3. 选图后的 UI 表现（建议）
选图成功、尚未开始上传时，建议统一呈现：
- 预览区：展示已选图片缩略图或全屏预览；双图业务需区分「图一 / 图二」标签或顺序说明。
- 可编辑项（若有）：分辨率、模板、文案提示等；与后端
create-task字段对应的选项应在此收集完毕。 - 主操作：例如「生成」「下一步」；点击前应做基础校验（必填项、文件是否存在）。
- 次要操作：「重新选图」清空当前选择回到选图入口；避免在上传中途允许再次选图 unless 有取消上传的完整逻辑。
- 状态：从点击「开始生成」到拿到
taskId之前，展示不可重复提交的加载态（按钮置灰、全屏 Loading 等），防止重复创建任务。
若客户端会在上传前做压缩（例如限制长边、JPEG 质量），失败时应有可理解的错误提示，并允许用户重试或重选。
4. 上传图片的数据流程（概念）
主路径可抽象为四步（与具体语言、类名无关）：
- （可选）压缩：对本地文件做尺寸/质量压缩，减少上传时间与流量。
- 申请预签名：请求服务端
upload-presigned-url类接口，携带文件名、内容类型、预期大小等；服务端返回 上传 URL、上传后文件在服务端的路径标识、以及 PUT 时需要的头信息。 - 直传对象存储：客户端对返回的 上传 URL 发起 HTTP PUT，请求体为图片字节流；请求头需与服务端约定一致（例如
Content-Type与附加头合并），避免签名失败。 - 创建任务：再请求
create-task类接口，将上一步得到的 文件路径（以及业务字段如分辨率、任务类型、模板名、提示词等）提交；响应中解析taskId。
双图源场景：对每张图重复「预签名 → PUT」，创建任务时分别填入「第一张 / 第二张」对应字段；若产品需要「仅首张作列表封面」，本地展示策略可与业务约定一致。
创建任务成功后，可选地把本次用于上传的本地文件拷贝到应用私有目录，按 taskId 命名，用于任务列表在远端封面尚未返回时的占位展示；该类缓存通常带过期清理策略。
5. 上传完成后界面如何跳转
建议的通用分支：
| 结果 | UI 行为 |
|---|---|
拿到 taskId |
进入进度页（或带进度条的全屏态），并开始对 taskId 轮询进度；同时可跳转到「我的任务」并插入一条「进行中」占位项。 |
| 上传或创建任务失败 | 停留在当前页或返回预览页，明确错误原因（网络、鉴权、业务拒绝等），提供重试与重选图。 |
| 需要离开当前页 | 若采用「列表驱动」体验，可在创建成功后直接跳到历史列表，并在列表项上展示进度；核心是用户始终能感知任务已创建且不会丢。 |
文生图（无用户文件）跳过上传步骤，在拿到 taskId 后的跳转逻辑可与上表一致。
6. 进度轮询与完成态 UI
- 轮询：按固定间隔请求
progress类接口（间隔需避免重叠请求，即上一帧结束再拉下一帧）；网络瞬时失败可有限次重试，超过阈值则提示用户检查网络或稍后从历史进入。 - 停止轮询：当出现可用结果 URL、或状态为成功/失败/超时/中止等等价终态时，应停止轮询，避免无效请求。
- 成功：展示结果图或跳转结果页；可提供保存、分享、再做一张等入口。
- 失败或超时：提示原因，提供重试（是否新建任务依产品）或返回模板/首页。
进度数据结构通常包含：任务标识、状态码或枚举、进度百分比、结果图 URL 等；界面应以「可展示结果」与「明确失败」为优先判断，避免仅依赖单一字段。
7. 任务列表与本地封面（概念）
- 远端列表：分页拉取「我的任务」类接口，展示缩略图、状态、时间等。
- 与本地封面合并：若创建成功时曾写入本地封面，列表在接口尚未返回远程封面 URL 时，可优先或回退显示本地文件，提升「刚提交就去看列表」的体验。
- 一致性：任务终态后应以服务端返回的 URL 为准；本地缓存可按时间与容量策略清理。
8. 集成方需对齐的要点（清单）
- 选图入口：相机 / 相册权限与取消流程。
- 选图后：预览、参数、防重复提交。
- 上传链：预签名 → PUT → create-task，PUT 头与 body 与服务端一致。
- 创建后：进度 UI 与
taskId维度的轮询停止条件。 - 列表：远端数据与可选的本地封面合并策略。
- 换皮差异：接口 host、鉴权、字段映射以各应用配置与对外文档为准。
9. 对外文档交叉引用
- 换皮应用功能清单、推荐封装方式：见各宿主仓库的开发手册中「图片 / 任务」相关章节。
- 接口字段与换皮命名：见各宿主仓库的客户端对接指南中
upload-presigned-url、create-task、progress、txt2img_create等关键词说明。