Genarrative/docs/experience/BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md

大鱼作品列表 items_json 兼容修复 2026-04-28

背景

大鱼吃小鱼作品列表在 server-rs 链路里由 SpacetimeDB procedure 返回 items_json，再由 spacetime-client 反序列化成 BigFishWorkSummaryRecord。

本轮出现的线上报错为：

big fish works items_json 非法: missing field `owner_user_id`

这说明：

1. 客户端 record 结构已经把 owner_user_id 当成必填字段。
2. 某些历史 items_json 仍是旧字段集，没有带上 owner_user_id。
3. 一旦直接按新结构强反序列化，整个 works 列表接口都会失败，而不是只丢失单字段。

根因判断

这不是前端展示问题，也不是 Axum 路由参数问题，而是：

1. SpacetimeDB procedure 输出 JSON 的结构发生过升级。
2. spacetime-client 映射层没有为旧 JSON 做向后兼容。
3. 作品列表是聚合读模型，一条旧记录就可能拖垮整批列表读取。

本次落地口径

本次只做最小风险修复，不改前端契约，不改现有表结构：

1. server-rs/crates/spacetime-client/src/mapper.rs

   • 大鱼 works 反序列化改为先读兼容结构。
   • owner_user_id 改为兼容层里的可缺省字段。

2. 私有 works 列表

   • 若旧 JSON 缺 owner_user_id，用当前查询的 owner_user_id 回填。
   • 这样不会破坏创作中心里依赖 ownerUserId 的恢复、归属和 key 逻辑。

3. 公开 gallery 列表

   • 若旧 JSON 缺 owner_user_id，先回填空串，保证列表接口不再整体失败。
   • 后续若公开画廊明确需要作者归属真相，再补模块端回填或数据修复。

4. 新增定向测试

   • 覆盖“私有 works 旧 JSON 缺字段仍可回填”
   • 覆盖“公开 works 旧 JSON 缺字段不再报错”

经验结论

以后只要是 procedure -> items_json -> client record 这类链路，都要默认遵守下面两条：

1. 聚合读模型的 JSON 字段升级不能假设全量历史数据同步完成。
2. spacetime-client 的映射层必须承担兼容旧 JSON 的责任，不能把结构升级风险直接抛给上层接口。

尤其是 works / gallery / library 这种平台入口级接口：

1. 允许单字段降级
2. 不允许整批列表因单字段缺失而 500 / 400

后续建议

如果后面继续演进大鱼 works 字段，推荐优先遵守：

1. 新增字段优先 Option 或兼容层解析。
2. 聚合 JSON 升级时同步补回归测试。
3. 如果字段已经进入前端关键逻辑，再决定是在模块端回填、客户端兜底，还是补历史数据迁移。