1

docs/technical/BIG_FISH_FORMAL_IMAGE_GENERATION_2026-04-23.md

@@ -0,0 +1,168 @@
+# 大鱼吃小鱼正式图片生成接入方案 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. 不修改现有占位图路径的兼容职责。