docs: split T-658 into four subtasks

docs/tasks/T-658a.md

@@ -0,0 +1,52 @@
+---
+id: T-658a
+title: 商品套图多图参考 cmhub 接口与提交 payload
+status: TODO
+phase: 7
+deps: [T-564]
+created: 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 张图片，超出部分由上游规则明确裁剪，并返回实际提交数量。
+- 保留异步提交、`Idempotency-Key`、轮询、自动重试、失败退点和现有并发语义。
+- 在提交前校验单图和总 payload 大小，避免 Base64 请求体过大；同一轮生成可按资产 ID缓存已编码内容，但必须有界。
+- 为 cmhub 请求增加真实接口契约测试：数组结构、最大数量、字段互斥、空项、错误响应和点数返回。
+- 若接口契约不满足，按中文错误提示失败，不静默回退到旧字段；是否支持旧服务端必须在发布前明确验证。
+
+## 验收要点
+
+- 单图请求只有 `images=[{"image_base64": ...}]`，没有顶层 `image_base64`。
+- 多图请求首元素是主图，后续是按顺序排列的参考图，最多 8 张。
+- 不能同时提交旧字段和新字段；空数组、空图片项、超过上限按可识别错误处理。
+- 每个生图请求的点数以 cmhub 返回值为准，确认现有点数展示没有按图片数量重复计算。
+- 异步任务的幂等、轮询和重试回归测试通过。
+
+## 边界（不改什么）
+
+- 不修改 cmhub 服务端协议、计费、并发和轮询策略。
+- 不修改提示词模板、数据库 schema、GUI 布局、蝦皮 CDP 流程。
+- 不实现图片语义分组或多 SKU 自动识别。
+
+## 验证
+
+```bash
+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
+```
+
+## 执行记录
+
+- 待实现。