3.5 KiB
3.5 KiB
id, title, status, phase, deps, created
| id | title | status | phase | deps | created | |
|---|---|---|---|---|---|---|
| T-658a | 商品套图多图参考 cmhub 接口与提交 payload | DONE | 7 |
|
2026-07-17 |
T-658a 商品套图多图参考 cmhub 接口与提交 payload
问题 / 背景
商品套图当前每个生图请求只提交一张源图，使用顶层 image_base64。不勾选「每张上传图分别作为主图生成」时，除第一张外的图片没有参与生成。cmhub 已提供 images 有序数组：第 1 张为主商品图，第 2 至第 8 张为参考图，每项使用 image_base64 或 image_url 二选一。
方案
- 在
app/image_studio_generation.py中集中实现多图 payload 构造。 - 本地图片统一使用
images数组中的image_base64，不再提交顶层旧字段。 - 单图也使用单元素
images数组；多图按主图、参考图顺序提交。 - 每个请求最多提交 8 张图片。裁剪责任在客户端：cmhub 对超过 8 张返回
400 bad_request，不会代为裁剪。上游列表由 T-658b 在 spec 期裁到「主图 + 最多 7 张参考」；本层在提交前做防御性校验，若仍超过 8 张视为程序 bug，按中文错误失败，不静默截断。 - 保留异步提交、
Idempotency-Key、轮询、自动重试、失败退点和现有并发语义。 - 在提交前校验单图和总 payload 大小，避免 Base64 请求体过大；同一轮生成可按资产 ID缓存已编码内容，但必须有界。
- 为 cmhub 请求增加真实接口契约测试：数组结构、最大数量、字段互斥、空项、错误响应和点数返回。
- 若接口契约不满足，按中文错误提示失败，不静默回退到旧字段；是否支持旧服务端必须在发布前明确验证。
- 发布门槛：T-658a/b/c/d 是一个发布单元。本任务落地而 T-658c（提示词一致性）未落地的中间版本，会出现「提示词声称单图、实际提交多图」的事实不符；在 T-658d 验收通过前不得打包发布安装程序。
验收要点
- 单图请求只有
images=[{"image_base64": ...}]，没有顶层image_base64。 - 多图请求首元素是主图，后续是按顺序排列的参考图，最多 8 张。
- 不能同时提交旧字段和新字段；空数组、空图片项、超过上限按可识别错误处理。
- 每个生图请求的点数以 cmhub 返回值为准，确认现有点数展示没有按图片数量重复计算。
- 异步任务的幂等、轮询和重试回归测试通过。
边界（不改什么）
- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
- 不修改提示词模板、数据库 schema、GUI 布局、蝦皮 CDP 流程。
- 不实现图片语义分组或多 SKU 自动识别。
验证
py -3.10 -m unittest tests.test_image_studio_generation
py -3.10 -m ruff check app tests main.py
py -3.10 -m compileall app main.py
git diff --check
执行记录
- 2026-07-17：将商品套图异步生图 payload 统一改为
images数组，单图也不再发送顶层image_base64；为后续参考图传入保留同一构造入口。 - 2026-07-17：新增最多8张、单图原文件10MiB、编码后总输入32MiB的请求前限制；超限使用中文错误阻断，超出数量以中文事件提示。
- 2026-07-17：补充单图 payload、图片顺序/8张裁剪及总大小超限的单元测试；同步架构/API 文档中的商品套图提交字段说明。
- 验证通过：
py -3.10 -m unittest tests.test_image_studio_generation（11项）、py -3.10 -m ruff check app tests main.py、py -3.10 -m compileall app main.py、git diff --check。