# 大鱼吃小鱼正式图片生成接入方案 2026-04-23

日期：`2026-04-23`

## 1. 文档目的

在 `2026-04-23` 早些时候，我们已经修复了 Big Fish 结果页“显示已生成但只能看到蓝色底图”的问题，先让占位图真正可见。

这份文档继续冻结下一步方案：把 Big Fish 结果页从“占位可见”升级为“模型正式出图”，并且复用仓库现有的 Rust 图片生成与 OSS 真相链，不再为 Big Fish 单独发明一套新资产系统。

## 2. 当前问题复盘

上一阶段虽然解决了“看不见图”的问题，但本质仍是占位链：

1. `api-server` 先写本地 `public/generated-big-fish/*` 占位 PNG。
2. `spacetime-module` 把 `big_fish_asset_slot.status` 写成 `ready`。
3. `asset_url` 写的是 `/generated-big-fish/...`。
4. 结果页能看到图片，但那只是占位预览，不是真实模型图。

这意味着：

1. 用户在结果页看到的“主图 / 动作 / 背景”仍不是正式资产。
2. `ready` 语义对 Big Fish 来说仍然偏弱，只表示“槽位上已有可预览资源”，不等同于“模型正式资产已落 OSS 真相链”。

## 3. 本次目标

本次把以下三类 Big Fish 资产切到正式图片生成链：

1. `level_main_image`
2. `level_motion`
3. `stage_background`

当前只接“正式静态图片生成”，不在这一轮扩视频、逐帧序列或动作 manifest。

原因是：

1. Big Fish 结果页当前只消费单个 `assetUrl`。
2. 运行态和结果页目前都按静态图预览设计。
3. 先把正式主图链闭合，比提前引入一套未被消费的视频协议更稳。

## 4. 统一真相链

Big Fish 正式图片生成统一复用现有 Rust 主链：

1. `api-server` 根据 Big Fish 草稿 prompt 调用 DashScope 文生图。
2. Rust 下载远端图片二进制。
3. Rust 上传到私有 OSS。
4. Rust 调用 `confirm_asset_object` 确认正式对象。
5. Rust 调用 `bind_asset_object_to_entity` 绑定 Big Fish 业务槽位。
6. Rust 再调用 Big Fish procedure，把 `big_fish_asset_slot.asset_url` 写成正式兼容路径。
7. 前端继续通过 `ResolvedAssetImage` 和 `/api/assets/read-url` 消费图片。

## 5. 路径策略

### 5.1 占位路径继续保留

占位图路径继续保持：

`/generated-big-fish/*`

它只代表：

1. 本地开发态占位可见资源。
2. 旧的最小预览兼容层。

### 5.2 正式图片使用新前缀

正式 Big Fish 图片统一写到新的 OSS legacy 兼容前缀：

`/generated-big-fish-assets/*`

这样可以同时满足：

1. 与仓库现有 `/generated-*` 兼容代理体系一致。
2. 不会被前端继续误判成占位图。
3. 后续可继续通过 `LegacyAssetPrefix`、`/api/assets/read-url`、`ResolvedAssetImage` 复用现有链路。

## 6. SpacetimeDB 语义调整

### 6.1 Big Fish 资产生成输入补充 `asset_url`

当前 `BigFishAssetGenerateInput` 只有：

1. `asset_kind`
2. `level`
3. `motion_key`
4. `generated_at_micros`

这会导致 procedure 无法知道 API 层是否已经拿到了正式 OSS 兼容路径。

因此本次补充：

1. `asset_url: Option<String>`

### 6.2 槽位写入规则

`build_generated_asset_slot(...)` 改为：

1. 若输入提供 `asset_url`，则直接写正式路径。
2. 若输入未提供 `asset_url`，才回退为 `/generated-big-fish/...` 占位路径。

这样做的原因是：

1. 允许同一个 Big Fish procedure 兼容“占位生成”和“正式生成”两种调用方式。
2. 不需要为了正式图片再新增一条平行 procedure。

## 7. Big Fish 与 `asset_object` 的绑定语义

Big Fish 不新增专门资产表，继续复用：

1. `asset_object`
2. `asset_entity_binding`

绑定原则：

1. `entity_kind` 使用 Big Fish 会话实体语义。
2. `entity_id` 使用 `session_id`。
3. `slot` 使用稳定可重建的槽位名。

推荐槽位命名：

1. `level_main_image:level-{n}`
2. `level_motion:level-{n}:{motion_key}`
3. `stage_background`

这样做可以：

1. 与 `big_fish_asset_slot` 一一对应。
2. 让后续真正做“重新生成覆盖旧资产”时有稳定槽位。

## 8. 前端识别语义

当前 `BigFishResultView` 仍用路径前缀判断是否为占位图：

1. 包含 `/generated-big-fish/` -> `占位已生成`
2. 否则 -> `已生成`

本轮先保留这个最小判定方式，原因是：

1. 正式图片会改走 `/generated-big-fish-assets/`。
2. 前端无需立即扩 contract 字段也能正确显示状态。

长期建议仍然是给 Big Fish 资产槽位补显式来源字段，但这不阻塞本轮正式出图。

## 9. 本轮验收标准

完成后需要满足：

1. `big_fish_generate_level_main_image` 会实际触发模型生成，并返回正式 Big Fish 图片。
2. `big_fish_generate_level_motion` 会实际触发模型生成，并返回静态动作预览图。
3. `big_fish_generate_stage_background` 会实际触发模型生成，并返回正式背景图。
4. SpacetimeDB 中对应 `big_fish_asset_slot.asset_url` 不再是 `/generated-big-fish/*`，而是 `/generated-big-fish-assets/*`。
5. 结果页状态从“占位已生成”切到“已生成”。
6. `/generated-big-fish-assets/*` 能通过 Rust 同源代理正确读取 OSS 私有对象。
7. `cargo check -p api-server`
8. `cargo check -p module-big-fish`
9. `cargo check -p spacetime-module`
10. `spacetime generate`
11. `cargo check -p spacetime-client`
12. `npm run check:encoding`

## 10. 本轮明确暂不做

1. 不做视频动作生成。
2. 不做序列帧 manifest。
3. 不新增 Big Fish 专属资产数据库表。
4. 不把 Big Fish 结果页改成复杂工作流编辑器。
5. 不修改现有占位图路径的兼容职责。