cmshoppe/docs/tasks/T-658a.md

id, title, status, phase, deps, created

id	title	status	phase	deps	created
T-658a	商品套图多图参考 cmhub 接口与提交 payload	TODO	7	T-564	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

执行记录

• 待实现。