4.3 KiB
4.3 KiB
大鱼吃小鱼结果页主图占位预览修复说明 2026-04-23
日期：2026-04-23
1. 问题现象
在“深海谜境 / 大鱼吃小鱼”结果页中，等级卡片会显示：
主图 已生成- 操作后会出现“已应用主图”感知
但实际结果页看不到角色主图，卡片里只有一张蓝色底图。
2. 排查结论
本次沿着“结果页展示 -> API action -> SpacetimeDB procedure -> 资产路径”全链检查后确认：
- 前端确实成功触发了
big_fish_generate_level_main_image - SpacetimeDB 侧确实把资产槽位状态写成了
ready - 但这条链路没有接真实图像模型，也没有接 OSS 真实资产对象
- 旧实现只回写一个
/generated-big-fish/...png占位 URL - 同时仓库里没有实际把这张占位图写到
public/generated-big-fish/... - 因此前端读到的是一个“看起来像图片地址、实际上没有真实文件”的路径
<img>加载失败后，卡片底层蓝色渐变背景暴露出来，于是用户只能看到蓝色图块
3. 根因拆解
3.1 状态成功过早
generate_big_fish_asset 当前最小实现只负责：
- 写
asset slot - 写
prompt snapshot - 标记
status = ready
它并不代表真实主图已经生成完成。
3.2 预览资源未真正落盘
旧实现会构造：
/generated-big-fish/{asset_kind}/{level_part}/{seed}.png
但没有同步在 public/generated-big-fish/... 写出对应文件。
3.3 结果页直接吃裸 assetUrl
Big Fish 结果页主图卡之前直接：
- 取
slot.assetUrl - 塞进
<img src=...>
一旦文件不存在，就只剩下卡片自己的蓝色渐变背景。
3.4 UI 文案误导
旧文案把当前阶段写成：
已生成已生成并设为正式资产
这会让用户自然理解为“真实主图已经出来了”，与当前最小实现不一致。
4. 本次修复策略
本轮不直接接真实模型生成，而是先把最小可见闭环补完整。
4.1 API action 写出可预览占位图
在 Rust api-server 的 Big Fish action 处理中：
- 复用拼图玩法“写本地可预览占位图”的方式
- 在调用
generate_big_fish_asset之前，先把 Big Fish 占位图真正写到：
public/generated-big-fish/...
- 保证 SpacetimeDB 里写入的占位 URL 至少对应一个真实可访问文件
4.2 结果页改用统一图片渲染组件
Big Fish 结果页主图和背景预览改为：
- 使用
ResolvedAssetImage - 统一走现有图片渲染链路
- 避免后续接 OSS / 旧 generated 路径兼容时再重复返工
4.3 状态文案改准
当前还是占位资产阶段，因此把结果页状态文案改为：
占位已生成生成并应用占位图
避免继续把“槽位 ready”误说成“真实主图已完成”。
4.4 结果页露出背景预览
除了等级主图卡，本轮顺手把场地背景卡也接上真实预览图渲染，避免出现：
- 状态显示完成
- 右侧仍只是一块纯渐变底图
5. 修复后的链路语义
修复后 Big Fish 当前资产链路语义明确为：
- 点击生成
api-server先写出本地可访问占位图spacetime-module写正式资产槽位和提示词快照- 前端读取
assetUrl并真实渲染预览
也就是说：
- 当前可以保证“用户看得见”
- 但仍然不是“真实模型图像生成”
- 后续真实模型 / OSS worker 接入后，再把占位图链替换成正式资产真相链
6. 验收标准
本次修复后需要满足：
- 结果页等级卡在主图生成后能直接看到真实可加载图片，不再只剩蓝色底图
- 场地背景生成后右侧卡片能看到真实可加载图片
- Big Fish 结果页图片渲染统一走现有图片组件，不再直接裸
<img>吃易失路径 - 当前 UI 文案不再把占位图误称为真实主图
- 若本地占位图写盘失败，则 action 不能继续回到“ready 成功”状态
7. 后续建议
下一阶段继续补 Big Fish 真实资产链时，建议按下面顺序推进：
- 先引入 Big Fish
asset_object + asset_entity_binding正式槽位设计 - 再接真实图片 / 动作生成 worker
- 最后把当前
/generated-big-fish/...本地占位路径迁为兼容层，而不是继续作为真相路径