支持素材生成上传参考图

图标素材生成支持上传普通参考图并提交到后端参考图数组。

UI设计图生成和UI素材提取支持上传参考图并写入生成输入记录。

同步前后端契约、OpenAPI、文档和相关单测。

docs/openapi/genarrative-external-v1.openapi.json

@@ -2778,7 +2778,14 @@
         "properties": {
           "referenceImageSrc": {
             "type": "string",
-            "description": "规范图/参考图 Data URL。"
+            "description": "规范图/参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+          },
+          "referenceImageSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "额外图标素材参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+            }
           },
           "iconDescriptions": {
             "type": "array",
@@ -2840,13 +2847,20 @@
         "properties": {
           "sourceImageSrc": {
             "type": "string",
-            "description": "UI 设计图 Data URL。"
+            "description": "UI 设计图 Data URL 或 objectKey。"
           },
           "model": {
             "type": "string",
             "default": "gemini-3.1-flash-image-preview",
             "description": "支持 gpt-image-2、gemini-3.1-flash-image-preview、nanobanana2、nano-banana。未传时默认使用 nanobanana。"
           },
+          "referenceImageSrcs": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "额外 UI 素材参考图 Data URL 或 objectKey；上传参考图优先提交 objectKey。"
+            }
+          },
           "aspectRatio": {
             "type": "string",
             "const": "1:1",

docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md

@@ -21,6 +21,7 @@
 - `从画布中选择` 只接受 `assetKind: "icon-spec"` 的图层；普通图片、其他类别图层和不携带标签的图片不绑定。
 - `新建图标规范` 复用现有图标规范生成表单。
 - `上传图片` 仅绑定到当前 UI 设计面板的图标规范参考，不自动添加为画布图层。
+- 图标规范之外可继续上传普通参考图，用于约束 UI 设计图的布局风格、配色或材质；普通参考图不替代图标规范。
 
 ## 生成参数
 
@@ -44,12 +45,14 @@
 ```
 
 生成请求固定使用 `gpt-image-2`。有参考图时走图片编辑请求；无参考图时走图片生成请求。
+前端提交时会把图标规范作为第一张参考图，并把用户上传的普通参考图按顺序追加到同一个 `referenceImageSrcs` 数组；上传参考图优先提交 `objectKey`。
 
 ## 提取素材
 
 - 点击浮动工具栏 `提取素材` 后，进入 UI 设计图素材框选编辑状态，不立即提交提取接口。
 - 框选状态参考微信截图工具栏布局，默认矩形框选，并支持矩形框选、椭圆框选和画笔自由框选三种工具。
 - 用户可在同一张 UI 设计图上多次框选；未至少框选一个区域时，工具栏 `提取` 按钮不可点击。
+- 可上传普通参考图辅助 UI 素材提取，用于约束被框选素材的风格、配色或材质；普通参考图会以 `objectKey` 随合成后的红框 UI 设计图一起提交。
 - 点击 `提取` 后，前端把所有框选的红色轮廓绘入原 UI 设计图，生成合成图片 Data URL，再提交到 `POST /api/editor/ui-designs/assets/extractions`。
 - 后端固定使用 `gpt-image-2` 图片编辑链路，并固定提示词：
 
@@ -66,5 +69,6 @@
 - 面板第一模块为图标规范，来源菜单包含三个动作。
 - 从画布选择时只能绑定图标规范图片。
 - 请求参数包含 `kind: "ui-design"`、`model: "gpt-image-2"`、比例、大小与可选参考图。
-- 生成图层信息面板展示 `用户输入` 与 `图标规范`。
+- 上传普通参考图后，请求参考图数组同时包含图标规范和普通参考图，生成图层信息面板展示 `用户输入`、`图标规范` 与普通参考图。
 - 选中 UI 设计图时浮动工具栏显示 `提取素材`；点击后进入红框素材框选状态，至少框选一个区域后才能调用固定 `gpt-image-2` 提取接口，画布同时出现 spritesheet 图集和拆分后的独立素材。
+- UI 素材提取面板上传普通参考图后，提取请求参考图数组同时包含红框 UI 设计图和普通参考图，生成图层信息面板展示 `UI设计图` 与普通参考图。

docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md

@@ -74,5 +74,6 @@
 - 默认 6 个素材描述会进入 prompt；用户在单个文本框中继续输入时最多解析 100 个素材描述。
 - 默认打开图标素材面板时选中 `nanobanana2 / 1:1 / 1K`；模型切换后，角色和图标素材面板之间沿用上次选择的模型。
 - 图标素材生成请求必须带 `model`、`aspectRatio` 和 `imageSize`；`nanobanana2` 请求体必须包含 `generationConfig.imageConfig.aspectRatio/imageSize`，`gpt-image-2` 请求必须包含文档映射后的 `size`。
+- 图标素材生成可以上传普通参考图；提交时图标规范图仍走 `referenceImageSrc`，普通参考图走 `referenceImageSrcs`，上传参考图优先提交 `objectKey`，并写入 `generationInputs.references`。
 - 生成成功后画布只出现一个已扣绿的透明 spritesheet 图集，不出现额外独立图标图层。
 - 生成图标素材提交体包含按模型和尺寸计算的 `priceMudPoints`；`nanobanana2 1K` 应为 `12`，`gpt-image-2 1K` 应为 `3`，`gpt-image-2 2K` 应为 `5`。若前端传入与后端计费配置不一致的值，后端返回 `priceMudPoints` 校验错误，不继续调用上游生成。