# 商品 AI 套图

本次交付负责人为当前集成会话，范围为 Web、API、Worker、contracts、database。经维护者确认三列右侧抽屉设计，新增契约而不改写已有选图/保存接口。依赖商品、SKU、正式素材、operations、outbox 与既有单图生图任务。验收：SKU 归属校验、最多 8 张底图、默认 4 张与可编辑逐张方案、异步智能规划、后台生成/取消/失败重试、结果回填表单及跨租户隔离。

所有接口要求当前工作空间鉴权。POST 均要求 UUID `Idempotency-Key`；异步创建返回 202 `{ data: ImageSuite }`，包含 `operation`，Outbox 仅保存任务 ID。GET 返回 200 同一资源，预览地址按次签发。接口不自动修改商品草稿。

- `POST /api/products/:productId/ai/suite-plans`：请求 `ImageSuitePlanInput`；异步调用 DeepSeek，生成 `shots`。失败显式返回任务错误，不将默认方案冒充 AI 规划。

智能规划请求在 `ImageSuiteInput` 上增加可选 `image_count`（整数 1–20，默认 4），以当前方案总张数作为预算；生成接口不接收此字段。Worker 使用 `.env` 的 `DEEPSEEK_API_KEY`、`DEEPSEEK_MODEL_NAME` 调用 DeepSeek，关闭 thinking 并要求 JSON。规划按当前 SKU 的商品资料、核心卖点/要求、实物参数、风格、比例及文字语言重新分配用途，必须精确返回预算张数，每类最多 5 张。每张承担一个不同的信息重点；首张为白底主图，优先仅 1 张（大预算可增加不同白底角度），其他用途按品类和可信资料选择，不强制插入场景、尺寸或材质图。底图 ID 不代表图像内容已被识别，不能据此编造细节；尺寸图必须有带单位的实物参数。方案经过共享契约和预算/主题校验，无效结果重新请求一次；取消后不回写结果，失败保留前端当前方案。不自动开始生图，用户核对后显式点击开始生成。
- `POST /api/products/:productId/ai/image-suites`：请求 `ImageSuiteInput` 加 `shots`；固化资料、规格、风格、配置、逐张方案并创建生图子任务。每张使用不超过 3 张底图，第一张是主体图。
- `GET /api/products/:productId/ai/image-suites`：`limit` 默认 20、最大 100、`cursor` 按创建时间及 ID 倒序分页，供重开抽屉恢复任务。
- `GET /api/products/:productId/ai/image-suites/:suiteId`：任务详情，包括逐张状态、脱敏失败诊断及结果正式素材。
- `POST /api/products/:productId/ai/image-suites/:suiteId/cancel`：取消规划或未完成的生图子任务；成功素材保留，Worker 不再回写取消项。
- `POST /api/products/:productId/ai/image-suites/:suiteId/retry`：只重试失败/取消的子任务，保留成功项；运行中的整套返回 409。规划失败重新创建规划任务。

`ImageSuiteInput`：`variant_id` 必填，必须属于当前商品；`reference_asset_ids` 1–8 个不重复正式图片；`product_name` 必填；`color`、`dimensions`（实物文字）、`weight`（实物文字）、`collected_info`、`selling_points` 可编辑。Web 尺寸由长/宽/高三个 `InputNumber` 组成，默认 CM，可切换 MM/M 并同步换算；提交时仍以带轴名称和单位的字符串保存到 `dimensions`，空轴省略。实物重量同样使用 `InputNumber`，默认 g，可切换 kg 并同步换算；提交到 `weight` 的仍是带所选单位的字符串（例如 `1.25 kg`），为空时不生成重量标注，已填写数值必须大于 0。`collected_info` 展示为「采集信息/描述」，`selling_points` 展示为「核心卖点/要求」；`ratio` 为 3:4（默认）、1:1、4:3；`language` 为 ru（默认）、zh、en、ar；`style_set` 1–5、`style_prompt` 为可选风格描述。

每个 `shot` 包含唯一 `id`、`category: white | scene | selling | other`、`type`、`theme`、`description`、`evidence` 与可选 `reference_asset_ids`（1–3，必须属于套图底图库）。每类最多 5 张，总共 1–20 张；缺少实物尺寸时不接受尺寸图。默认 4 张：1 白底主图 + 1 场景展示图 + 1 核心卖点图 + 1 细节特写图（分类数量为 1/1/2/0）；缺资料时以真实外观/细节取代无依据的尺寸、材质、对比或配件图。

`ImageSuite` 包含 `id`、`product_id`、`variant_id`、`purpose: plan | generate`、`status: queued | running | succeeded | partial | failed | cancelled`、`input`、`shots`、`items`、`error_code`、`created_at`、`completed_at`、`operation`。`items` 为逐张 `shot_id` + `edit_id` + 既有 `MediaAiEdit`。生成任务已完成但部分失败返回 partial，可保留成功图并重试失败项。统一图片任务入口将整套作为一项 `kind: ai_suite` 展示，子任务不重复出现；成功子图自然进入当前商品 AI 生图记录。

取消和重试使用整套资源锁；数据库复合外键强制 SKU/商品/工作空间与子任务同商品归属。底图库关联表强制素材工作空间归属；所有表 FORCE RLS。触发器依据子任务事实汇总整套进度及 operation，队列不是事实来源。

规划请求示例（UUID 为示例值）：

```json
{
  "variant_id": "11111111-1111-4111-8111-111111111111",
  "reference_asset_ids": ["22222222-2222-4222-8222-222222222222"],
  "product_name": "可调角度台灯",
  "collected_info": "灯头可调节角度",
  "selling_points": "突出角度调节，画面简洁",
  "image_count": 4,
  "ratio": "3:4",
  "language": "ru"
}
```

返回 `202 { data: ImageSuite }`，`purpose=plan`、`status=queued`、`input.image_count=4`，不创建生图子任务。轮询完成后 `status=succeeded`、`shots.length=4`；每项包含主题、画面描述、资料依据及参考图 ID。若配置缺失，任务为 failed，错误码为 `DEEPSEEK_NOT_CONFIGURED`，诊断提示检查 Worker 的 API Key 和模型名称。

规划校验失败分别使用 `AI_SUITE_PLAN_SCHEMA_INVALID`、`AI_SUITE_PLAN_COUNT_MISMATCH`、`AI_SUITE_PLAN_MAIN_IMAGE_INVALID`、`AI_SUITE_PLAN_DUPLICATE_THEME`、`AI_SUITE_PLAN_DIMENSIONS_UNVERIFIED`；结果保存失败使用 `AI_SUITE_PLAN_SAVE_FAILED`，未知执行异常使用 `AI_SUITE_PLAN_FAILED`。Worker 对每次校验失败及最终失败打印安全的结构化日志，包含任务 ID、阶段、尝试序号和字段校验路径；最终诊断保存至 operation.result.failure（内部诊断，不新增 HTTP 字段）。不保存商品资料、模型原文或凭据。第二次规划携带具体校验规则及路径，仍须通过完整校验，不能截断或用默认方案替换。