补齐生成中间产物持久化与拆图提示
图标和UI图集拆分失败时保留主图集并在内联、队列及刷新路径提示 角色、图片修改、图标UI和角色动作链路把可恢复中间产物写入项目与素材库 外部生成摘要新增独立告警字段并清理成功任务的历史错误 同步共享契约、SpacetimeDB迁移与绑定、OpenAPI、设计文档和回归测试
This commit is contained in:
@@ -3285,6 +3285,13 @@
|
||||
"string",
|
||||
"null"
|
||||
]
|
||||
},
|
||||
"assetFolderId": {
|
||||
"type": [
|
||||
"string",
|
||||
"null"
|
||||
],
|
||||
"description": "角色动作绿幕预览视频写入账号素材库的文件夹；省略时写入默认项目素材文件夹。"
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
|
||||
@@ -16,12 +16,13 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-13 图片画布多产物生成任务必须回填全部产物
|
||||
## 2026-07-13 图片画布多产物生成任务必须保存全部可恢复产物
|
||||
|
||||
- 背景：角色形象、图标 spritesheet 和 UI 素材提取会先得到带纯色背景的原图，再执行抠图或拆分；此前原图只登记到 OSS，后端完成快照只把后处理结果放到画布，用户无法在画布继续使用同一任务的完整产物。
|
||||
- 决策：凡一次资产生成任务产生多个可复用产物，所有产物都必须登记为 `editor_project_resource` 并由同一次后端 `canvasCompletion` 写入权威画布快照，不能只返回最终产物或由前端临时补图。角色形象、图标 spritesheet 和 UI 素材提取至少同时保留纯色背景原图与透明后处理结果；UI 素材提取还继续保留拆分素材。生成器 `generatedLayerId` 始终锚定主后处理结果，附属产物在主结果右侧错开放置，避免重叠并保持后续改造入口语义不变。没有项目上下文时继续只持久化 OSS / asset object，不虚构画布资源。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、图片画布生成完成快照、角色形象 / 图标 spritesheet / UI 素材提取链路和图片画布文档。
|
||||
- 验证方式：覆盖多产物画布布局、主结果锚定和资源去重的定向 Rust 测试，并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
|
||||
- 背景：角色形象、图标 spritesheet 和 UI 素材提取会先得到带纯色背景的原图，再执行抠图或拆分；图片修改会先得到模型对齐尺寸的原始输出，角色动作会先得到绿幕预览视频，再抽帧和抠图。此前部分原始产物只登记到 OSS，或者要等后处理成功后才进入项目资源，用户无法在失败后找回已经生成成功的内容。
|
||||
- 决策：凡一次资产生成任务产生多个可恢复产物，后端必须先把上游已返回的中间产物写入 OSS、`asset_object`、项目资源和账号素材库，再执行抠图、尺寸恢复、抽帧或拆分；未指定素材文件夹时进入默认“项目”文件夹。角色形象、图标 spritesheet 和 UI 素材提取同时保留纯色背景原图与透明后处理结果；图片修改保留模型原始输出与尺寸恢复结果；角色动作把绿幕预览视频作为一个可复用素材保存，逐帧源图继续留在同一任务 OSS 路径，不把 32 至 48 帧逐张灌入素材库。普通图片、去背景、音频等没有独立上游中间产物的任务不制造重复副本。
|
||||
- 画布与降级：有项目上下文的图片多产物继续由同一次 `canvasCompletion` 写入权威画布快照，生成器 `generatedLayerId` 锚定主后处理结果。图标和 UI 图集自动拆分是 best-effort；识别或切片持久化失败仍完成整张透明图集，并在 inline、队列轮询和刷新后任务列表中提示非阻断 warning，不得借用失败错误字段。
|
||||
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`character_animation_assets.rs`、外部生成任务摘要、图片画布完成快照、账号素材库和前端生成提示。
|
||||
- 验证方式：覆盖中间产物登记先于后处理、默认素材文件夹、图集拆分降级、inline / queue warning 和主结果锚定的定向测试，并运行 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、前端定向测试、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。
|
||||
|
||||
## 2026-07-12 泥点充值收敛为四档并统一资产入口
|
||||
|
||||
@@ -270,13 +270,13 @@ npm run check:server-rs-ddd
|
||||
- Rust 结构体：`ExternalGenerationJob`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
|
||||
- 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，但用户可见任务列表、价格、状态、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
|
||||
- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用；其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行和受控维护读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得再返回或解析这两个 payload。
|
||||
- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用；图标图集生成和 UI 素材提取成功但自动拆分降级时，worker 的 `result_payload_json` 只额外保存有界的 `warning.code/reason`，不保存 spritesheet、切片列表或媒体 URL。其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行和受控维护读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得再返回或解析这两个 payload。
|
||||
|
||||
### `external_generation_job_summary`
|
||||
|
||||
- Rust 结构体：`ExternalGenerationJobSummary`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
|
||||
- 用途：外部生成正式任务列表的轻量投影，按 `job_id` 保存 owner、来源、状态、价格、有界错误摘要、通知确认时间、各阶段时间和入队时提取的 `request_prompt`，不包含 request/result payload、worker lease 或 dedupe 内部字段。错误摘要统一拒绝内联媒体并限制为 2048 字符；列表在单次 owner 扫描中同时计数并只保留请求 limit 的固定大小 top-N，不得先收集全量历史再截断。enqueue、claim、renew、complete、fail 事务同步投影；acknowledge 只更新该轻量表并写审计事件，后续主任务同步必须保留已有确认时间，禁止为了写确认时间加载 / 重写大 payload 行。BFF 的列表、状态和确认只调用 summary procedure。历史终态任务由迁移操作员的游标分批 maintenance procedure 在压缩 payload 时同步回填摘要，正式列表不得为兼容旧数据回扫完整主表。
|
||||
- 用途：外部生成正式任务列表的轻量投影，按 `job_id` 保存 owner、来源、状态、价格、有界错误摘要、有界非阻断告警 `warning_message`、通知确认时间、各阶段时间和入队时提取的 `request_prompt`，不包含 request/result payload、worker lease 或 dedupe 内部字段。错误与告警摘要都不复制内联媒体并限制为 2048 字符；`warning_message` 由完成任务的轻量 `result_payload_json.warning.reason` 提取，complete 和历史 backfill 共用同一构建路径。列表在单次 owner 扫描中同时计数并只保留请求 limit 的固定大小 top-N，不得先收集全量历史再截断。enqueue、claim、renew、complete、fail 事务同步投影；acknowledge 只更新该轻量表并写审计事件，后续主任务同步必须保留已有确认时间，禁止为了写确认时间加载 / 重写大 payload 行。BFF 的列表、状态和确认只调用 summary procedure。历史终态任务由迁移操作员的游标分批 maintenance procedure 在压缩 payload 时同步回填摘要，正式列表不得为兼容旧数据回扫完整主表。
|
||||
- 正式读取 procedure 为 `get_external_generation_job_summary_and_return`、`list_external_generation_job_summaries_and_return` 和 `acknowledge_external_generation_job_summaries_and_return`。历史维护 procedure 为 `compact_external_generation_job_payloads_and_return` 与 `backfill_external_generation_job_summaries_and_return`，仅 migration operator 可调用；运维入口统一使用 `npm run spacetime:external-generation:maintain -- ...`，默认 dry-run、单批最多 25 条。B-tree cursor 选择阶段最多反序列化 `limit + 1` 行，apply 再按主键逐条读取选中行；怀疑存在单行异常巨型 JSON 时必须先使用 `--limit 1`。payload 压缩额外固定使用 `source_module = editor-canvas` 的复合 cursor 索引，不得静默改写其它玩法历史任务。
|
||||
|
||||
### `external_generation_job_event`
|
||||
|
||||
@@ -117,6 +117,8 @@
|
||||
- 保存时在现有画布布局数组中追加 `itemType: "generation-dialog"` 项，记录生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和 `generatedLayerId`。
|
||||
- 生成成功后仍保留生成器快照；画布渲染优先用 `generatedLayerId` 锚定到成品图层，不再重复显示灰色占位框。
|
||||
- 一次生成任务产生多个可复用产物时，全部产物都必须由后端登记为项目资源并随同一次完成快照加入画布，不能只保留最终产物或由前端临时追加。角色形象、图标 spritesheet 和 UI 素材提取至少同时回填纯色背景原图与透明后处理结果；UI 素材提取继续一并回填拆分素材。`generatedLayerId` 仍锚定透明后处理主结果，附属产物从主结果右侧开始错开放置。
|
||||
- 多产物任务的可恢复中间产物还必须进入账号素材库，未传 `assetFolderId` 时落默认“项目”文件夹，并在抠图、尺寸恢复、抽帧或拆分前完成登记。图片修改保存模型对齐尺寸的原始输出；角色动作把绿幕预览视频保存为一个素材，逐帧绿幕源图只保留在同一任务 OSS 路径，避免素材库一次新增 32 至 48 张帧图。普通图片、去背景和音频等没有独立上游中间产物的任务不重复复制最终结果。
|
||||
- 图标和 UI 图集自动拆分属于非阻断附加动作；识别或切片持久化失败时整张透明图集仍完成并回填，前端通过 warning toast 提示用户可手动重试。inline 响应、worker 队列终态和刷新后的任务列表必须使用同一 warning 语义，不能把已完成图集标记为失败。
|
||||
- 图片、视频和音频生成结果都要写入账号级素材库；视频 / 音频结果由后端持久化到 OSS 并回传 `objectKey` / `assetObjectId`，前端保存素材库时一并记录，后续预览和再次加入画布走统一换签链路。
|
||||
- 刷新项目后，画布需要同时恢复图层、生成器快照和生成输入框跟随关系。
|
||||
|
||||
|
||||
@@ -61,7 +61,8 @@
|
||||
仅提取被红色框框选的素材并整理成spritesheet，图集背景必须使用后端自动决策出的抠图背景色。纯色背景必须平整无纹理、无渐变、无阴影、无地面、无环境、无道具，方便后续扣除背景；素材自身不要出现与背景色相同或相近的描边、底板、投影或反光。
|
||||
```
|
||||
|
||||
- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 按默认 `segModel=birefnet` 透明化，并复用图标素材的连通域拆分能力；未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`。
|
||||
- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS、项目资源和账号素材库，再调用 BgFilter 按默认 `segModel=birefnet` 透明化；透明 spritesheet 同样先进入 OSS、项目资源和账号素材库，再复用图标素材的连通域拆分能力。调用方未指定素材文件夹时落默认“项目”文件夹。
|
||||
- UI 素材自动拆分与图标图集一致，属于 best-effort 附加动作。未知素材数量时按从上到下、从左到右自动命名为 `素材 1`、`素材 2`；识别或切片持久化失败仍返回整张透明图集和 `sliceWarning`，前端显示非阻断 warning toast，用户可手动重试。
|
||||
- 前端先把 spritesheet 原图作为 `assetKind: "icon-spritesheet"` 图集图层放在 UI 设计图右侧，再把拆分出的独立素材作为 `assetKind: "icon"` 图标图层继续放到画布。图集图层同样提供 `拆分图集` 工具栏按钮，可使用相同连通域规则重新拆分。
|
||||
|
||||
## 验收点
|
||||
|
||||
@@ -61,7 +61,7 @@
|
||||
|
||||
- 后端收到 spritesheet 后先把带解析后纯色背景的源图写入 OSS，再调用 BgFilter 透明化；请求字段包含 `screenColor` 和 `segModel`，前端用户路径固定提交 `screenColor=auto` 与默认 `birefnet`，后端仍识别内部保留的 `anime-seg`，但该选项不对用户可见。
|
||||
- 带背景原图和去背后的透明 spritesheet 都先同时写入 OSS、项目资源和账号素材库，再按 alpha 连通域和素材描述顺序执行附加拆分；调用方未指定素材文件夹时统一落默认“项目”文件夹。每个成功切片单独写入 OSS、项目资源和账号素材库，`sourceResourceId` 指向透明图集资源。
|
||||
- 自动拆分是生成后的 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；用户可在图集工具栏手动重试。
|
||||
- 自动拆分是生成后的 best-effort 附加动作，不参与图集生成的成功判定。连通域识别或切片持久化失败时，接口仍返回并回填整张透明图集，`iconImageSrcs=[]`，并通过 `sliceWarning.code/reason` 暴露非阻断原因；前端在 inline、worker 队列完成和刷新恢复三条路径统一显示 warning toast，用户可在图集工具栏手动重试。
|
||||
- 响应通过 `iconImageSrcs` 返回成功切片素材；自动生成使用用户输入的素材描述命名，UI 设计提取和手动拆分按从上到下、从左到右自动命名为 `素材 N`。
|
||||
- 手动拆分调用 `POST /api/editor/icon-spritesheets/slices`，只允许读取当前用户项目中的 `icon-spritesheet` 资源，不调用图片生成 provider，不扣除泥点。输入限制为单边最多 `4096` 像素、总像素最多 `2048×2048`，单次最多持久化 `64` 个切片；超限在任何切片写入前拒绝。
|
||||
|
||||
|
||||
@@ -147,7 +147,7 @@
|
||||
### Prompt 与生成契约
|
||||
|
||||
- 前端提交到 `POST /api/editor/character-animations/generations`。
|
||||
- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长。角色图片已经持久化到 OSS 时，`sourceImageSrc` 必须优先传 `objectKey`；只有未持久化的本地临时图片才允许传 Data URL。
|
||||
- 请求必须带上角色图片来源、原始尺寸、动画描述、分辨率、画面比例、帧数和时长，并可通过 `assetFolderId` 指定中间视频素材落点。角色图片已经持久化到 OSS 时，`sourceImageSrc` 必须优先传 `objectKey`；只有未持久化的本地临时图片才允许传 Data URL。
|
||||
- 后端使用角色图片作为首帧和尾帧参考，模型固定映射到 `doubao-seedance-2-0-fast-260128`。
|
||||
- 后端路由兼容旧 Data URL 请求并单独放宽 JSON body limit 到 `12MB`，但该限额只作为兼容兜底，不作为新链路默认传大图的方式。
|
||||
- 后端 prompt 使用以下固定骨架，并把面板输入追加到 `动作描述：` 后：
|
||||
@@ -160,7 +160,7 @@
|
||||
|
||||
### 抽帧与 OSS 存储
|
||||
|
||||
- 视频生成完成后，后端按面板选择抽取对应帧数：`32`、`40` 或 `48`。
|
||||
- 视频生成完成后，后端先把带纯色背景的预览视频登记为 OSS 私有对象、`asset_object`、项目资源和账号素材，再按面板选择抽取对应帧数：`32`、`40` 或 `48`。未传 `assetFolderId` 时进入默认“项目”素材文件夹；后续抽帧或抠图失败不能抹掉这份已经生成成功的可恢复视频。
|
||||
- 抽帧采样必须按目标帧数预留视频尾部安全步长，例如 `32帧·4秒` 最后一帧采 `3.875s`，避免 FFmpeg 在尾点附近返回成功但输出 `0` 帧。
|
||||
- 每帧必须先把带自动决策纯色背景的源图写入 OSS，再优先调用阿里云通用抠图输出透明背景 PNG；阿里云失败时降级执行本地 `editor_green_screen`，并按同一次生成已选定的 `screenColor` 去背。
|
||||
- 抽帧结果写入 OSS，并返回帧路径、帧尺寸、帧数、fps、预览视频路径、模型、价格和实际 prompt。
|
||||
|
||||
Reference in New Issue
Block a user