Genarrative/docs/experience/RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md

RPG 发布作品广场刷新修复 2026-04-25

背景

已发布 RPG 作品会进入 custom_world_profile，并由 SpacetimeDB 模块同步到公开读模型 custom_world_gallery_entry。平台首页和分类页不直接读取“我的作品”，而是共同消费 /api/runtime/custom-world-gallery 返回的公开作品列表。

本次问题表现为：结果页显示发布完成后，作品没有立即出现在平台首页和分类页。

修复原则

1. publish_world 必须写入真实作者公开信息。

   • Axum 层在执行 publish_world 前补充 authorPublicUserCode 与 authorDisplayName。
   • SpacetimeDB 模块发布时优先使用 payload 中的作者公开信息，再退回历史兜底。

2. 发布完成后必须刷新公开广场列表。

• 前端 executePublishWorld 等待发布 operation 完成后，同时刷新 refreshPublishedGallery() 与 refreshCustomWorldWorks()。
• 首页和分类页都复用 publishedGalleryEntries，因此刷新 gallery 后两个页面会同步看到新发布作品。

多玩法公开列表补充

• 平台首页 / 分类页不是只展示 RPG 作品，也需要展示已经发布到公开接口的 Puzzle 作品。
• Puzzle 已有 /api/runtime/puzzle/gallery 公开接口；平台入口额外读取该接口，并把 PuzzleWorkSummary 映射为首页卡片模型。
• 首页 / 分类页按 rpg:{ownerUserId}:{profileId} 与 puzzle:{ownerUserId}:{profileId} 去重后按发布时间排序。
• 点击 RPG 卡片仍进入 RPG 公开详情；点击 Puzzle 卡片进入现有 Puzzle 广场详情，不复用 RPG 详情链路。

3. 历史已发布作品必须能自动补齐 gallery 投影。
   • 公开列表读取 list_custom_world_gallery_entries 前，会扫描 custom_world_profile 中已发布且未删除的 profile。
   • 若已发布 profile 缺少 custom_world_gallery_entry，或缺少公开作品码 / 作者百梦号，会先补齐公开字段并同步 gallery 投影。
   • 这样旧版本发布成功但未落入广场读模型的作品，在下一次首页 / 分类页读取公开列表时会自动出现。

经验

• 作品发布链不能只看“我的创作”列表，必须同时检查公开读模型。
• 分类页的数据不是独立接口，修首页公开列表通常也会影响分类页。
• Agent 发布链和普通 library profile 发布链要共享公开作者字段语义，避免同一个 gallery card 在不同发布入口下字段不一致。
• 已发布 profile 与 gallery 投影不是同一张表，线上修复时要考虑历史数据补投影，不能只修新增发布路径。