Genarrative/docs/technical/RPG_CREATION_HISTORY_ASSET_REUSE_2026-04-26.md

RPG 创作编辑器历史素材复用设计

日期：2026-04-26

1. 本次目标

编辑场景角色与编辑场景图片时，玩家可以复用历史生成素材：

1. 场景角色形象区删除 基于预设素材修改 入口，以及它打开的预设拼装编辑下游。
2. 场景角色形象区新增 使用历史素材，打开独立素材面板。
3. 场景图片的幕背景配置新增 使用历史素材，打开独立素材面板。
4. 历史素材面板需要展示所有账号过去生成过的对应类型素材，并明确标注素材归属账号。
5. 选择素材后直接应用到当前角色或当前幕背景，不触发新一轮生成。

2. 数据真相

历史素材不从前端草稿 profile 扫描，也不从预设素材目录扫描。

历史素材统一来自 SpacetimeDB 的 asset_object 表：

使用位置	asset_kind	应用字段
场景角色形象	character_visual	imageSrc、generatedVisualAssetId
场景幕背景	scene_image	backgroundImageSrc、backgroundAssetId

asset_object.owner_user_id 是归属账号标注主源。为空时 UI 标注为 未记录账号，不能隐藏归属栏。

3. 后端接口

新增只读接口：

GET /api/assets/history?kind=character_visual
GET /api/assets/history?kind=scene_image

返回字段只包含前端选择所需脱敏信息：

1. assetObjectId
2. assetKind
3. imageSrc
4. ownerUserId
5. ownerLabel
6. profileId
7. entityId
8. createdAt
9. updatedAt

asset_object 仍保持 private table。读取历史列表必须通过 SpacetimeDB procedure + Axum facade，不能让前端直接订阅整表。

4. SpacetimeDB 设计

module-assets 新增：

1. AssetHistoryListInput
2. AssetHistoryEntrySnapshot
3. AssetHistoryListResult

spacetime-module 新增 procedure：

list_asset_history_and_return(input: AssetHistoryListInput) -> AssetHistoryListResult

实现规则：

1. 只允许 character_visual、scene_image。
2. 按 asset_kind 过滤。
3. 按 created_at 倒序返回。
4. 默认最多返回 120 条，允许调用方传更小 limit。
5. image_src 由 object_key 转为兼容代理路径：/{object_key}。

5. 前端交互

历史素材面板为独立弹层，不在当前面板下方展开。

角色历史素材卡片：

1. 展示素材图。
2. 展示归属账号。
3. 展示创建时间。
4. 点击 使用 后写入当前草稿角色：
   • imageSrc = imageSrc
   • generatedVisualAssetId = assetObjectId
   • generatedAnimationSetId = undefined
   • animationMap = undefined

场景历史素材卡片：

1. 展示 16:9 预览。
2. 展示归属账号。
3. 展示创建时间。
4. 点击 使用 后写入当前幕：
   • backgroundImageSrc = imageSrc
   • backgroundAssetId = assetObjectId

6. 非目标

1. 不新增图片生成模型能力。
2. 不把历史素材复制成新 OSS 对象。
3. 不修改旧预设素材目录。
4. 不恢复 server-node 或 PostgreSQL 链路。