# 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. 后端接口

新增只读接口：

```text
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：

```rust
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 链路。