重构图标规范与图集生成链路

新增图标规范独立队列任务并将参数补全纳入统一计费操作
将图标图集生成和手工拆分迁入独立图标模块并复用公共生图能力
将图标规范引用收紧为项目资源或素材 ID
同步 SpacetimeDB 引用解析契约、External OpenAPI、前端与 Agent 提交链路
补充相关回归测试和长期架构约定

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

@@ -3360,19 +3360,19 @@
       "EditorIconSpritesheetGenerationRequest": {
         "type": "object",
         "required": [
-          "referenceImageSrc",
+          "referenceId",
           "iconDescriptions"
         ],
         "properties": {
-          "referenceImageSrc": {
+          "referenceId": {
             "type": "string",
-            "description": "图标规范的稳定引用：当前账号的 objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。"
+            "description": "当前账号中已登记为 icon-spec 的项目资源 ID 或素材 ID。只接受 ID，不接受 objectKey、图片 URL、Data URL 或 Blob URL。"
           },
           "referenceImageSrcs": {
             "type": "array",
             "items": {
               "type": "string",
-              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceImageSrc 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
+              "description": "额外图标素材参考图的稳定引用：objectKey、项目资源 ID 或素材 ID；本地临时图必须先上传 OSS。禁止 Data URL / Blob URL。referenceId 占用 1 张 provider 容量，因此 gpt-image-2 最多再提交 4 张、nanobanana2 最多再提交 8 张；超限返回 400，不会静默截断。"
             },
             "maxItems": 8
           },

docs/project-memory/shared-memory/decision-log.md

@@ -6637,3 +6637,11 @@
 - 图标规范 HTTP handler 在调用文本 LLM 前，先通过可复用图片请求预检完成参考图稳定性、owner 授权、Provider 配置与运行时定价校验；随后补齐 `ExtraParam` 与最终 prompt，并继续走既有 `editor_image_generation` inline / queue 分流，不新增图标规范专用 worker job。最终执行仍重新校验请求，以处理排队期间发生的权限或资源变化。
 - 图标图集主规范引用由通用 SpacetimeDB procedure `resolve_editor_reference_and_return` 在同一事务快照内解析和校验 owner。ID 使用资源 / 素材主键；objectKey 按规范化 `image_src="/<objectKey>"` 索引读取唯一行，并使用 `asset_object(bucket, object_key)` 复合索引校验对象 owner。procedure 不接收业务 / 存储类型 allowlist，复用既有 `EditorProjectResourceSnapshot` / `EditorAssetSnapshot` 返回完整单行，不新增图标专属 DTO，也不再拉取完整项目和素材库；`icon-spec` 业务类型与游戏类型由 API 业务代码校验和提取。缺失引用、跨 owner、asset object 不匹配、业务类型错误、元数据解析与数据库错误全部失败关闭；仅“合法记录没有 genre”允许返回 `None`。
 - 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-08-06 图标规范与图标图集使用独立任务及 ID-only 主规范引用
+
+- 本条取代上一条“不新增图标规范专用 worker job”和“图标图集主规范允许 objectKey”的结论。图标规范生成使用独立 `editor_icon_spec_generation` job kind；队列保存原始强类型业务参数，worker 在统一计费操作预扣成功后执行 ExtraParam LLM、构建最终 prompt，再进入共享图片生成和既有后处理 / 持久化链。余额不足不调用文本 LLM，执行失败沿用统一退款；普通 `editor_image_generation` 的 DTO、payload 与执行行为保持不变。
+- `editor_project_icon.rs` 独立承接图标规范、图标 spritesheet、自动切片和手工拆分。普通图片模块只暴露可复用的 prompt builder 执行入口与强类型 provider 请求分流；nanobanana、无参考图 generation、有参考图 edit 的选择集中在同一个 helper，图标图集复用该 helper，不复制 provider 分支。
+- 图标规范生成的可选参考图与图标图集的必选主规范统一使用 `referenceId`，只接受当前 owner 的项目资源 ID 或账号素材 ID，不接受 objectKey、URL 或临时 key。SpacetimeDB `resolve_editor_reference_and_return` 因而只接收 `reference_id` 并按两张表主键查询，删除 `image_src` 二级索引。图标图集的普通附加参考图 `referenceImageSrcs` 仍允许 owned objectKey、项目资源 ID 或素材 ID，并继续走既有 owner 校验与真实图片下载链。
+- External v1 图标图集请求与 OpenAPI 同步改为必填 `referenceId`。前端和 Editor Agent 优先传正式 resource ID，其次传 asset ID；本地临时 ID、objectKey 和图片地址不得回退成主规范引用，未登记时明确失败并要求先上传或登记。
+- 关联：`server-rs/crates/api-server/src/editor_project_icon.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`docs/openapi/genarrative-external-v1.openapi.json`。

docs/project-memory/shared-memory/pitfalls.md

@@ -338,7 +338,7 @@
 
 - 现象：画板生成、快速编辑、图标素材或 UI 素材提取如果允许直接提交 generated objectKey，用户只要知道其他账号的私有 objectKey，就可能让 api-server 签名读取并送给外部生成供应商。
 - 原因：Data URL/Blob URL 只允许停留在浏览器临时态，正式编辑器引用必须先上传并经统一 resolver 校验归属。
-- 处理：所有私有对象引用在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口（生成 / 重绘 / 图标 / UI 提取等交给 provider 的路径）再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
+- 处理：普通图片、重绘、图标图集附加参考图和 UI 提取等允许 objectKey 的私有对象引用，在读取字节或签发 URL 前统一走 `resolve_editor_reference_object_key_for_owner(state, owner_user_id, source)`，先在当前账号的项目资源、素材库资产或 `asset_object` 中匹配 owner / bucket / key。只有确实需要图片字节的入口再走 `parse_editor_reference_image`（内部仍先 resolve，再下载 OSS 字节）；手动去背景等只签发短期 URL 的入口不要 `parse` 整图。图标规范生成的可选参考图与图标图集的主规范引用是更窄的业务契约：只接受正式 `referenceId`（项目资源 ID / 素材 ID），不得回退 objectKey、URL 或临时 key；图标图集的额外 `referenceImageSrcs` 才继续沿用通用 owned objectKey 规则。手动去背景还要恢复源模型时，object key 解析、所有权校验和源模型回溯必须复用同一轮账号项目 / 素材快照，项目与素材快照各最多读取一次；不得先走通用 resolver 全量读取，再为模型回溯重复拉取完整画布和素材库。图标素材等额外参考图必须真实传到 provider，不只写 metadata；图片快速编辑当前不开放额外参考图，若后续重开入口也必须沿用同一归属校验。
 - 验证：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_reference`，并用前端 workflow 测试覆盖 `referenceImageSrcs` 进入图标生成请求；若快速编辑重开额外参考图，再补对应请求覆盖。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/spacetime-client/src/assets.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`。
 

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -630,7 +630,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - `generation_inputs_json` 包络契约：`fields` / `references` 是图片信息读取的用户可见生成输入快照；顶层允许保存后端内部结果扩展。现有 `screenColorHex` 保存实际背景色，角色、图标图集和 UI 图集抠图派生资产使用 `mattingProvider` / `mattingModel` 保存实际成功的处理后端与模型。BgFilter 保存本次 `seg_model`，阿里云通用抠图保存 `Aliyun Matting / segment-common-image`，本地键色保存 `Genarrative Local / screen-color-keying`。同源画布 BFF 的角色、图标和 UI 请求由前端自动提交 `screenColor=auto` 与默认 `segModel=birefnet`，其中 `segModel` 是不可由用户选择的请求控制字段，不进入 `generationInputs`；`background_mode` 和 `cross_check` 只属于 api-server 到 worker 的内部 RPC。External OpenAPI 不开放 `segModel`。上述内部结果字段不写入 `fields`，普通用户（包括素材 owner）与匿名公开读取均不得取得；普通用户响应还必须省略素材顶层 `provider` 和内部处理 `model`，但保留正常用户可见 `model` 与其他合法的顶层功能字段。后台管理和服务端审计可读取原始值。过滤只作用于普通用户 / 公开响应边界，不修改素材或精选快照，因此历史数据无需迁移。
 - 普通用户生成结果契约：图片、图标图集、视频、音频和角色动画的完成响应与新建画布图层均不返回或写入生成 provider；项目资源、素材、精选和 Agent 紧凑结果使用同一读取边界。真实 provider 只保留在持久化、tracking / tracing 和后台管理原始审计中。该规则针对生成供应商元数据，不改变直传票据等必须由客户端执行的存储协议字段。
 - 普通用户错误契约：手动去背景和角色动作透明化的原始服务端错误可能包含 BgFilter、分割模型或 provider 细节；Owner HTTP 响应与外部任务状态必须按 job kind 返回稳定业务文案，原始错误只保留在任务记录、tracing 与后台审计。
-- 索引：`by_editor_project_resource_project_id`、`by_editor_project_resource_owner_user_id`、`by_editor_project_resource_image_src`。
+- 索引：`by_editor_project_resource_project_id`、`by_editor_project_resource_owner_user_id`。
 
 ### `editor_asset_folder`
 
@@ -644,7 +644,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - Rust 结构体：`EditorAsset`
 - 源码：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`
 - 说明：图片画布账号级素材表，保存用户上传 / 生成素材的名称、文件夹、图片读取地址、可选封面 `thumbnail_src`、OSS 引用、尺寸、来源类型、prompt、provider、真实操作 `task_id`、可选后台归组 `group_task_id`、拆分批次预期数量 `group_task_expected_asset_count`、`asset_kind`、`generation_inputs_json`、可选 `source_resource_id` 和 `generation_cost_mud_points`。`prompt` 固定表示规范化后的用户原始意图，供跨资源搜索和用户侧元数据使用；provider 实际返回的改写只写 `actual_prompt`，提交给 provider 的系统 / 工程化 prompt 不得写入 `prompt`。角色透明图、图标透明图和自动切片等派生产物继承源用户 prompt，并用 `source_resource_id`、`generation_inputs_json`、provider / asset kind 表达处理来源。归组字段追加在表尾并默认 `None`，只用于稳定派生任务的后台分组，不替代 `task_id`；批次是否初始完整以独立完成事实为准，不按当前剩余素材数反推。素材在同一账号的所有项目中可见；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `asset_folder_id` 时负责创建账号级生成素材并返回 asset 快照，若同次生成也创建了 `editor_project_resource`，则把该 `resource_id` 写入 `source_resource_id`。角色动作生成保留原始绿幕视频中间素材，同时把最终帧序列作为一条 `asset_kind = character-animation` 素材入库：首帧写入 `image_src` / `thumbnail_src`，完整帧列表、FPS、时长和预览视频写入 `generation_inputs_json.characterAnimation`，不把每帧拆成独立素材。生成视频会抽取首帧封面写入 `thumbnail_src`，素材库和再次放入画布时用它作为 video poster。素材库快照通过 `asset_id` 回查对应 `editor_showcase_asset`，供左侧素材菜单展示 `pending` / `approved` / `rejected` 审核状态；公开事实不落在账号素材表，素材库只发起提交审核。素材放入画布时复制为 `editor_project_resource` 并由图层引用 resourceId，画布从 resource / asset 级元数据恢复素材类别和用户可见生成输入快照。
-- 索引：`by_editor_asset_owner_user_id`、`by_editor_asset_folder_id`、`by_editor_asset_image_src`。
+- 索引：`by_editor_asset_owner_user_id`、`by_editor_asset_folder_id`。
 
 ### `editor_asset_group_source_provenance`