From d7fe4137f4728e3dbdfa5e640563852c2902b39d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Sat, 8 Aug 2026 15:41:45 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E9=BD=90=E5=A4=96=E9=83=A8=E5=9B=BE?= =?UTF-8?q?=E7=89=87=E7=BC=96=E8=BE=91=E5=9C=BA=E6=99=AF=E7=99=BD=E5=90=8D?= =?UTF-8?q?=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 在 External v1 权威契约中加入 scene 有效类型 用 OpenAPI 扩展精确声明完整快速编辑白名单 强化契约测试并同步外部接入文档 --- docs/openapi/genarrative-external-v1.openapi.json | 12 +++++++++++- ...端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md | 2 +- .../crates/api-server/src/external_editor_api.rs | 14 ++++++++++++++ 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/openapi/genarrative-external-v1.openapi.json b/docs/openapi/genarrative-external-v1.openapi.json index bbacf4468..59e3f54be 100644 --- a/docs/openapi/genarrative-external-v1.openapi.json +++ b/docs/openapi/genarrative-external-v1.openapi.json @@ -1088,7 +1088,17 @@ ], "operationId": "editExternalEditorImage", "summary": "重绘/调整编辑器图片素材", - "description": "主来源只接受当前账号已登记的项目资源 ID 或素材 ID（sourceReferenceId）；objectKey、URL、Data URL 与 Blob URL 即使归属当前账号也返回 400。服务端从命中的业务记录派生 canonical objectKey、assetObjectId 与权威类型，只允许普通静态图片（类型为 null）、spec、character、icon-spritesheet、icon-spec、publication-material 或 ui-design，其他及未知类型返回 400。提供 targetLayerId 时必须同时提供 projectId，目标图层必须关联有效项目资源；双方都有 assetObjectId 时必须相同，否则回退比较 canonical bucket/objectKey。同一对象的来源默认类型与目标资源默认类型冲突、目标有效类型或媒体类型不允许、来源或目标不存在/越权/缺少对象时均返回 400，任务不会入队。referenceImageSrcs 仍只作为辅助参考图。", + "description": "主来源只接受当前账号已登记的项目资源 ID 或素材 ID（sourceReferenceId）；objectKey、URL、Data URL 与 Blob URL 即使归属当前账号也返回 400。服务端从命中的业务记录派生 canonical objectKey、assetObjectId 与权威类型；快速编辑的完整有效类型白名单为普通静态图片（类型为 null）、spec、character、icon-spritesheet、icon-spec、publication-material、ui-design 和 scene，其他及未知类型返回 400。提供 targetLayerId 时必须同时提供 projectId，目标图层必须关联有效项目资源；双方都有 assetObjectId 时必须相同，否则回退比较 canonical bucket/objectKey。同一对象的来源默认类型与目标资源默认类型冲突、目标有效类型或媒体类型不允许、来源或目标不存在/越权/缺少对象时均返回 400，任务不会入队。referenceImageSrcs 仍只作为辅助参考图。", + "x-genarrative-allowed-effective-asset-kinds": [ + null, + "spec", + "character", + "icon-spritesheet", + "icon-spec", + "publication-material", + "ui-design", + "scene" + ], "security": [ { "ExternalApiKey": [] diff --git a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md index 7cb94bb2f..57cc0521a 100644 --- a/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md +++ b/docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md @@ -214,7 +214,7 @@ SpacetimeDB procedure： 外部生成接口复用站内编辑器已有 DTO、入队器和 worker executor，不维护第二套生成语义： -- 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则，但 External handler 固定只入队。External v1 图片修改必须提交当前账号已登记的项目资源 ID 或素材 ID 作为 `sourceReferenceId`；上传对象必须先登记为项目资源或素材。objectKey、URL、Data URL、Blob URL 以及旧 `sourceImageSrc/sourceResourceId/assetKind` 字段均返回 `400`。服务端分别按资源 ID 与素材 ID 主键窄查，双表冲突、未命中、越权或对象记录无效均失败关闭，类型只接受业务记录派生的 `null / spec / character / icon-spritesheet / icon-spec / publication-material / ui-design`。请求带 `targetLayerId` 时必须同时带 `projectId`；目标图层必须关联有效项目资源，来源与目标优先比较 `assetObjectId`，缺失时比较 canonical `(bucket, objectKey)`，来源默认类型还必须与目标资源默认类型一致。入队载荷保存版本化权威快照，worker 执行前再次定点解析并拒绝身份或类型漂移；仅以素材 ID 编辑时不伪造项目资源关系。主站和 External 的通用图片入口共用场景专用合同边界校验，禁止用 `kind = scene` 或 `assetKind = scene` 绕过后端场景 Prompt 组装；场景专用 handler 自己构造规范请求，不受该通用入口校验影响。 +- 图片生成 / 重绘 / 规范图 / 宣发图 / UI 设计图复用 `/api/editor/images/generations` 与 `/api/editor/images/edits` 的校验、模型归一、计费和持久化规则，但 External handler 固定只入队。External v1 图片修改必须提交当前账号已登记的项目资源 ID 或素材 ID 作为 `sourceReferenceId`；上传对象必须先登记为项目资源或素材。objectKey、URL、Data URL、Blob URL 以及旧 `sourceImageSrc/sourceResourceId/assetKind` 字段均返回 `400`。服务端分别按资源 ID 与素材 ID 主键窄查，双表冲突、未命中、越权或对象记录无效均失败关闭，快速编辑的完整有效类型白名单为 `null / spec / character / icon-spritesheet / icon-spec / publication-material / ui-design / scene`，OpenAPI 的 `x-genarrative-allowed-effective-asset-kinds` 必须与后端白名单精确一致。请求带 `targetLayerId` 时必须同时带 `projectId`；目标图层必须关联有效项目资源，来源与目标优先比较 `assetObjectId`，缺失时比较 canonical `(bucket, objectKey)`，来源默认类型还必须与目标资源默认类型一致。入队载荷保存版本化权威快照，worker 执行前再次定点解析并拒绝身份或类型漂移；仅以素材 ID 编辑时不伪造项目资源关系。主站和 External 的通用图片入口共用场景专用合同边界校验，禁止用 `kind = scene` 或 `assetKind = scene` 绕过后端场景 Prompt 组装；场景专用 handler 自己构造规范请求，不受该通用入口校验影响。 - 图标 spritesheet 和 UI 设计图素材提取复用站内拆分逻辑，生成图集后按连通域切片，并把图集与切片都按请求写入项目资源和素材库。 - 角色动画、视频、音效和背景音乐复用站内编辑器生成链路；请求携带 `assetFolderId` 时按站内规则写入素材库，音频类外部调用使用 API Key 所属账号作为 asset owner。 - API Key 管理接口仍只属于登录态个人中心，不进入外部 OpenAPI JSON。 diff --git a/server-rs/crates/api-server/src/external_editor_api.rs b/server-rs/crates/api-server/src/external_editor_api.rs index 5dd834af9..2d2cde360 100644 --- a/server-rs/crates/api-server/src/external_editor_api.rs +++ b/server-rs/crates/api-server/src/external_editor_api.rs @@ -2012,6 +2012,19 @@ mod tests { json!(false) ); let image_edit_operation = &parsed["paths"]["/api/external/v1/editor/images/edits"]["post"]; + assert_eq!( + image_edit_operation["x-genarrative-allowed-effective-asset-kinds"], + json!([ + null, + "spec", + "character", + "icon-spritesheet", + "icon-spec", + "publication-material", + "ui-design", + "scene" + ]) + ); assert!( image_edit_operation["description"] .as_str() @@ -2019,6 +2032,7 @@ mod tests { && description.contains("sourceReferenceId") && description.contains("assetObjectId") && description.contains("bucket/objectKey") + && description.contains("scene") && description.contains("未知类型") && description.contains("返回 400")) );