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

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

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`。