1

docs/experience/BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md

@@ -0,0 +1,65 @@
+# 大鱼作品列表 `items_json` 兼容修复 2026-04-28
+
+## 背景
+
+大鱼吃小鱼作品列表在 `server-rs` 链路里由 SpacetimeDB procedure 返回 `items_json`，再由 `spacetime-client` 反序列化成 `BigFishWorkSummaryRecord`。
+
+本轮出现的线上报错为：
+
+```text
+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. 如果字段已经进入前端关键逻辑，再决定是在模块端回填、客户端兜底，还是补历史数据迁移。

docs/experience/README.md

@@ -31,3 +31,4 @@
 - [RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md](./RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md)：记录 RPG 发布后首页 / 分类页公开作品列表刷新链路。
 - [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
 - [BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md](./BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md)：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
+- [BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md](./BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md)：记录大鱼作品列表 `items_json` 字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。