feat: support multi-image image generation

progress.md

@@ -1991,3 +1991,13 @@
   - 输入数量、单图和总大小、SSRF、敏感词、无定价等校验均在预扣前完成；不保存 base64、输入图片内容或 provider raw。
 - 中转站直连验收证据：使用 `gpt-image-2`、两张本地图片调用 `/v1/images/edits`，HTTP 200，约 73 秒返回 `data[0].b64_json`，解码后图片约 2.04 MB；输出保存于工作区外的 `D:\chengma\cmhub-relay-tests\multi-images-edits-result.bin`。该结果确认重复 `image` 字段可被接受，但主图 / 参考图语义仍由 T-620 的服务端固定 prompt 和真实两张明显不同图片验收确认。
 - 验证：任务登记完成后执行文档 diff 检查；未运行代码测试，因为本轮未改实现。
+
+## 2026-07-17 完成：T-620 图生图支持单图 / 多图主图与参考图
+
+- 接口与输入：`POST /api/v1/generate/image`、`POST /api/v1/generate/image/tasks` 新增有序 `images`。每项必须且只能给出 `image_url` 或 `image_base64`；旧单图字段继续兼容，但不得与 `images` 混用。图片数量、单图和总大小分别由 `IMAGE_MAX_INPUT_IMAGES=8`、`IMAGE_MAX_INPUT_IMAGE_BYTES=10485760`、`IMAGE_MAX_INPUT_TOTAL_BYTES=33554432` 控制。
+- 角色语义：用户 prompt 先经既有敏感词审核；只要有输入图片，服务端才追加不可由调用方覆盖的规则，明确第 1 张为主商品图、第 2 张及之后仅为参考图。一次请求仍按既有 image 别名 / 分辨率预扣一次，校验、审核、SSRF、下载与解码都在预扣前；失败、重试与僵任务退款继续复用原有幂等链路。
+- Provider：`MultimodalImage` 增加文件名，生成接口增加有序 `images` 参数。Chat Completions 按顺序生成图片内容段；Gemini 按顺序生成 inlineData；JSON 图片 Provider 发送有序 `image_urls`；`images_edits` 多图使用重复的 multipart `image` 字段，单图仍保持原请求形状。
+- 异步：新增 `api.0003_image_generation_task_input` 与 `ImageGenerationTaskInput(task, ordinal, image, mime_type, filename)`。提交时只保存解码后的输入文件和非敏感元数据，不保存 base64 原文；worker 按序恢复所有输入。没有子记录时仍读取历史任务的 `input_image`。
+- 安全回归：完整 `GenerateApiTests` 首次运行 53 条时发现旧 `image_url` 会因新多图单图限制而绕过 `IMAGE_URL_MAX_BYTES`。已修复为 URL 下载取既有 URL 上限与请求上下文单图上限中的较小值，恢复旧接口保护语义。
+- 文档：同步更新 `README.md`、`00-ai-start-here.md`、`02-requirements.md`、`04-architecture.md`、`api.md`、`routes.md`、`env.md`、`deployment.md`、`current-state.md` 与任务看板，明确多图请求格式、主图 / 参考图语义、异步存储和 Nginx 请求体配置。
+- 验证：`C:/Python312/python.exe -m compileall -q apps config`、`manage.py check`、`manage.py makemigrations --check --dry-run` 通过；迁移 `api.0003_image_generation_task_input` 已应用到当前开发库。Provider 测试 13 条通过；序列化器多图、空数组与混用边界通过；目标 API 6 条通过（同步多图、URL+base64 混合、混用拒绝、超限拒绝、异步存储 / worker 恢复、旧 URL 上限）。完整 53 条 `GenerateApiTests` 的修复后重跑受远程 MySQL 测试库耗时影响超过 5 分钟未完成，未出现新的失败输出；此前完整运行唯一失败已修复并由目标回归用例确认。中转站两图 `images/edits` 重复 multipart `image` 直连验收此前返回 HTTP 200 和有效图片，作为真实上游多文件传输证据。