Merge remote-tracking branch 'origin/master' into codex/fix-draft-result-back-target

2026-05-26 16:45:57 +08:00
parent 4e14301b33 3909a1ef10
commit 5fb51f4430
47 changed files with 2678 additions and 79 deletions
--- a/docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md
+++ b/docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md
@@ -0,0 +1,92 @@
+# 统一公开作品 ReadModel 设计
+
+更新时间：`2026-05-26`
+
+## 背景
+
+各玩法原本各自维护 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 等公开投影。它们继续保留为 source view 和兼容路径，但公开列表与公开详情的主读模型需要跨玩法统一，避免 `api-server` 在 HTTP 热路径里为每个玩法各写一套拼装逻辑。
+
+## 统一契约
+
+公开列表主读模型：
+
+- `public_work_gallery_entry`
+
+公开详情摘要主读模型：
+
+- `public_work_detail_entry`
+
+统一字段只保留公开层契约所需内容：
+
+- `source_type`
+- `work_id`
+- `profile_id`
+- `source_session_id`
+- `public_work_code`
+- `owner_user_id`
+- `author_display_name`
+- `world_name`
+- `subtitle`
+- `summary_text`
+- `cover_image_src`
+- `cover_asset_id`
+- `theme_tags`
+- `play_count`
+- `remix_count`
+- `like_count`
+- `published_at_micros`
+- `updated_at_micros`
+- `sort_time_micros`
+- `detail_payload_json`
+
+其中 `detail_payload_json` 只承载平台详情页展示扩展，不承载正式 runtime 配置、玩法规则或草稿真相。
+
+## 来源与兼容
+
+统一 public view 由现有玩法 source view 组装：
+
+- `puzzle_gallery_card_view`
+- `puzzle_gallery_view`
+- `custom_world_gallery_entry`
+- `jump_hop_gallery_card_view`
+- `jump_hop_gallery_view`
+- `wooden_fish_gallery_card_view`
+- `wooden_fish_gallery_view`
+- `match_3_d_gallery_view`
+- `square_hole_gallery_view`
+- `visual_novel_gallery_view`
+- `big_fish_gallery_view`
+- `bark_battle_gallery_view`
+
+规则是：
+
+- 旧 view 保留，不删除。
+- 旧 view 退到底层 source / 兼容职责。
+- 新 `public_work_*` view 是 `api-server` 公开列表 / 详情的统一主读模型。
+- 旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容，由 BFF mapper 把统一 cache 再映射回当前 DTO。
+- 旧详情 / runtime / 点赞 / 游玩 / Remix 仍走玩法专用路径。
+
+## 订阅与路由
+
+`spacetime-client` 当前长期订阅：
+
+- `SELECT * FROM public_work_gallery_entry`
+- `SELECT * FROM public_work_detail_entry`
+- `SELECT * FROM public_work_play_daily_stat`
+- 各玩法 source view 作为兼容缓存和旧路径支撑
+
+`api-server` 当前新增统一公开路由：
+
+- `GET /api/public-works`
+- `GET /api/public-works/{publicWorkCode}`
+
+旧 route 继续保留，由 BFF 从统一 cache 映射回旧 DTO 形状。
+
+## 验证
+
+- `npm run spacetime:generate`
+- `npm run check:spacetime-schema`
+- `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
+- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
+- `npm run typecheck`
+- `npm run check:encoding`
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -131,7 +131,7 @@ npm run check:server-rs-ddd
 3. 删除字段、改名、重排字段、改类型或修改字段属性前，必须先询问用户并确认迁移计划。
 4. Vec 字段不要直接写无法 const 求值的 default；需要默认空集合时优先使用 `Option<Vec<T>>` 加 `#[default(None::<Vec<T>>)]`，业务层归一为空数组。
 5. 运行态读表必须按已声明索引访问。只要 table 上存在覆盖查询前缀的 `#[index(...)]` 或主键 / unique accessor，列表、详情、快照组装和计数都先用对应 accessor `.filter(...)` / `.find(...)`，再在内存中处理索引无法覆盖的残余条件；不得用 `.iter().filter(...)` 扫整表替代现成索引。
-6. 面向公开列表的只读投影优先做成 public view / public 读模型表，并由 `api-server` 的 `spacetime-client` 长期订阅后读本地 cache。短期不把作品列表整体交给浏览器前端直接订阅；不要让 HTTP 列表接口每次请求都调用 procedure 重新组装全量列表。需要请求时间窗口的轻量统计可订阅公开统计表后在 `api-server` 本地聚合，需要写入副作用的详情、点赞、游玩记录仍可走 procedure / reducer。中期如要让前端可选直连订阅，只能新增或统一稳定的专用 public read model，例如 `public_work_gallery_entry`，并保持字段、排序键、公开权限和降级语义由后端投影定义；前端不得直接订阅 `puzzle_work_profile`、`custom_world_profile` 等领域源表，也不得自己做 join、聚合或权限逻辑。首屏、排序、字段归一、权限降级和 HTTP fallback 仍由 `api-server` BFF 维持。
+6. 面向公开列表的只读投影优先做成 public view / public 读模型表，并由 `api-server` 的 `spacetime-client` 长期订阅后读本地 cache。跨玩法公开作品统一主读模型是 `public_work_gallery_entry` 和 `public_work_detail_entry`；各玩法既有 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 保留为 source view 和兼容路径。短期不把作品列表整体交给浏览器前端直接订阅；不要让 HTTP 列表接口每次请求都调用 procedure 重新组装全量列表。需要请求时间窗口的轻量统计可订阅 `public_work_play_daily_stat` 后在 `api-server` 本地聚合，需要写入副作用的详情、点赞、游玩记录仍走玩法 procedure / reducer。前端不得直接订阅 `puzzle_work_profile`、`custom_world_profile` 等领域源表，也不得自己做 join、聚合或权限逻辑。首屏、排序、字段归一、权限降级和 HTTP fallback 由 `api-server` BFF 维持。
 7. 多列索引按 SpacetimeDB 绑定生成的元组参数直接传入，例如 `.filter((source_type, profile_id, played_day))`；前缀查询只传前缀元组，例如 `.filter((scope_kind, scope_id.as_str()))`。不要为了绕过类型问题退回整表遍历。
 8. procedure result 必须返回 typed snapshot / typed value。`spacetime-client` mapper 不得再通过 `row_json/session_json/work_json/items_json/run_json/event_json/feedback_json: Option<String>` 做跨层 JSON 字符串传输，也不得在 mapper 里反序列化旧 `*JsonRecord` 兼容结构。业务内部持久化字段如 `profile_payload_json`、`levels_json` 等不属于 procedure result 载荷例外，仍按各自表契约处理。
 9. 修改后运行：
@@ -304,7 +304,7 @@ npm run check:server-rs-ddd
 - Rust view：`big_fish_gallery_view`
 - 返回类型：`Vec<BigFishWorkSummarySnapshot>`
 - 源码：`server-rs/crates/spacetime-module/src/big_fish/session.rs`
- 说明：大鱼吃小鱼公开广场列表投影，只从 `Published` creation session 组装公开卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM big_fish_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'big-fish'` 后，从本地 cache 构造 `/api/runtime/big-fish/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_big_fish_works` procedure；个人作品列表、详情、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
+- 说明：大鱼吃小鱼公开 source 投影，只从 `Published` creation session 组装公开卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。玩法旧 gallery 路径保留兼容 shape；个人作品列表、详情、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。

 ### `chapter_progression`

@@ -350,7 +350,7 @@ npm run check:server-rs-ddd

 - Rust 结构体：`CustomWorldGalleryEntry`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
- 作用：自定义世界公开作品列表读模型。`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM custom_world_gallery_entry` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'custom-world'`，`/api/runtime/custom-world-gallery` 从本地 cache 排序并聚合 `recentPlayCount7d`，不再每个 HTTP 请求调用 `list_custom_world_gallery_entries` procedure。旧 procedure 只用于兼容旧库缺少 gallery 读模型行时的一次性同步兜底。
+- 作用：自定义世界公开 source 读模型。统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该投影并映射成跨玩法契约；`/api/runtime/custom-world-gallery` 保留旧 HTTP shape，并从统一 public cache 映射回旧 DTO。旧 procedure 只用于兼容旧库缺少 gallery 读模型行时的一次性同步兜底。

 ### `custom_world_profile`

@@ -402,14 +402,14 @@ npm run check:server-rs-ddd
 - Rust view：`jump_hop_gallery_card_view`
 - 返回类型：`Vec<JumpHopGalleryCardViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
- 说明：跳一跳公开广场列表卡片投影，只暴露 `publication_status = Published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM jump_hop_gallery_card_view` 后，从本地 cache 构造跳一跳公开列表响应。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。
+- 说明：跳一跳公开列表 source 投影，只暴露 `publication_status = Published` 的作品卡片字段；统一公开列表主路径通过 `public_work_gallery_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。

 ### SpacetimeDB view：`jump_hop_gallery_view`

 - Rust view：`jump_hop_gallery_view`
 - 返回类型：`Vec<JumpHopGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
- 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；公开列表主路径优先使用 `jump_hop_gallery_card_view`。
+- 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。

 ### `wooden_fish_agent_session`

@@ -437,14 +437,14 @@ npm run check:server-rs-ddd
 - Rust view：`wooden_fish_gallery_card_view`
 - 返回类型：`Vec<WoodenFishGalleryCardViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/wooden_fish.rs`
- 说明：敲木鱼公开广场列表卡片投影，只暴露 `publication_status = published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM wooden_fish_gallery_card_view` 后，从本地 cache 构造敲木鱼公开列表响应。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。
+- 说明：敲木鱼公开列表 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表主路径通过 `public_work_gallery_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。

 ### SpacetimeDB view：`wooden_fish_gallery_view`

 - Rust view：`wooden_fish_gallery_view`
 - 返回类型：`Vec<WoodenFishGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/wooden_fish.rs`
- 说明：敲木鱼公开详情兼容投影，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效和飘字配置；公开列表主路径优先使用 `wooden_fish_gallery_card_view`。
+- 说明：敲木鱼公开详情兼容投影，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效和飘字配置；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。

 ### `match3d_agent_message`

@@ -471,7 +471,7 @@ npm run check:server-rs-ddd
 - Rust view：`match3d_gallery_view`
 - 返回类型：`Vec<Match3DGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/match3d.rs`
- 说明：抓大鹅公开广场列表投影，只暴露 `publication_status = published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM match_3_d_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'match3d'` 后，从本地 cache 构造 `/api/runtime/match3d/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_match3d_works` procedure；个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
+- 说明：抓大鹅公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。

 ### `npc_state`

@@ -604,14 +604,14 @@ npm run check:server-rs-ddd
 - Rust view：`puzzle_gallery_view`
 - 返回类型：`Vec<PuzzleWorkProfile>`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
- 说明：拼图广场公开详情兼容投影，只暴露 `publication_status = Published` 的作品，但返回完整 `PuzzleWorkProfile`，包含 levels / anchor_pack 等详情级字段；公开列表主路径不再订阅该 view。
+- 说明：拼图广场公开详情 source / 兼容投影，只暴露 `publication_status = Published` 的作品，但返回完整 `PuzzleWorkProfile`，包含 levels / anchor_pack 等详情级字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。

 ### SpacetimeDB view：`puzzle_gallery_card_view`

 - Rust view：`puzzle_gallery_card_view`
 - 返回类型：`Vec<PuzzleGalleryCardViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
- 说明：拼图广场公开列表卡片投影，只暴露前端列表卡片需要的公开字段，不携带 levels / anchor_pack 等详情级载荷；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM puzzle_gallery_card_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle'` 后，从本地 cache 构造 `/api/runtime/puzzle/gallery` 响应，并在本地按当前请求时间聚合 `recentPlayCount7d`，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
+- 说明：拼图公开列表 source 投影，只暴露前端列表卡片需要的公开字段，不携带 levels / anchor_pack 等详情级载荷；统一公开列表主路径通过 `public_work_gallery_entry` 消费该 view，`/api/runtime/puzzle/gallery` 保留旧 HTTP shape，并从统一 public cache 映射回 `PuzzleGalleryResponse`。

 ### 拼图公开列表 HTTP 窗口缓存

@@ -624,26 +624,31 @@ npm run check:server-rs-ddd

 `spacetime-client` 建立每个池连接时会等待下列订阅初始同步：

+- `SELECT * FROM public_work_gallery_entry`
+- `SELECT * FROM public_work_detail_entry`
+- `SELECT * FROM bark_battle_gallery_view`
 - `SELECT * FROM puzzle_gallery_card_view`
+- `SELECT * FROM jump_hop_gallery_card_view`
+- `SELECT * FROM wooden_fish_gallery_card_view`
 - `SELECT * FROM custom_world_gallery_entry`
 - `SELECT * FROM match_3_d_gallery_view`
 - `SELECT * FROM square_hole_gallery_view`
 - `SELECT * FROM visual_novel_gallery_view`
 - `SELECT * FROM big_fish_gallery_view`
- `SELECT * FROM jump_hop_gallery_card_view`
-
-下列订阅用于统计或配置缓存，订阅失败不会让公开列表连接整体不可用，调用方保留兼容兜底：
-
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle'`
+- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'jump-hop'`
+- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'wooden-fish'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'custom-world'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'match3d'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'square-hole'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'visual-novel'`
 - `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'big-fish'`
+- `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'bark-battle'`
 - `SELECT * FROM creation_entry_config`
 - `SELECT * FROM creation_entry_type_config`
+- `SELECT * FROM asset_object`

-拼图、自定义世界、抓大鹅、方洞挑战、视觉小说和大鱼吃小鱼的公开列表 HTTP 路由都从订阅 cache 读取公开 read model / view。各玩法的个人作品列表、详情、发布、点赞、游玩记录、Remix 和其它需要鉴权或写入副作用的路径继续走 procedure / reducer；不要为了公开列表性能把这些 owner-specific 或 mutation 语义混进 public view。
+跨玩法公开作品列表 / 详情主读模型是 `public_work_gallery_entry` 与 `public_work_detail_entry`。拼图、自定义世界等旧玩法公开列表 HTTP 路由保留原响应 shape，由 BFF mapper 从统一 public cache 映射回当前 DTO；旧 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 继续作为 source view 和兼容缓存。各玩法的个人作品列表、详情、发布、点赞、游玩记录、Remix 和其它需要鉴权或写入副作用的路径继续走 procedure / reducer；不要为了公开列表性能把这些 owner-specific 或 mutation 语义混进 public view。

 `GET /api/creation-entry/config` 和入口熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
 入口配置快照包含 start card、类型弹窗、活动横幅和入口类型列表；入口类型列表新增 `category_id`、`category_label`、`category_sort_order` 后，后台 upsert、`shared-contracts`、`module-runtime` 和 `spacetime-client` binding 必须同步，旧迁移 JSON 通过 `migration.rs` 默认值兼容。
@@ -652,7 +657,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；

 结构化创作和 RPG 的 LLM JSON 链路默认不启用 Responses `web_search`；只有在明确需要联网增强时，才通过 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED` 显式打开。否则未开通工具的上游会先吐自然语言再返回 `ToolNotOpen`，这类失败要按上游工具不可用处理，不要误判成模型返回结果解析失败。

-未来可选：若发现页、推荐流和各玩法广场需要统一给浏览器前端直接订阅公开作品列表，只新增 / 统一专用 public read model，例如 `public_work_gallery_entry`。该 read model 必须是后端投影后的公开作品卡片契约，覆盖作品类型、公开作品号、标题、摘要、封面、作者展示名、排序键、公开统计和入口开关后的可见性，不暴露玩法领域源表 row shape。前端可选择订阅这个稳定投影来减少 HTTP 拉取，但不能订阅 `puzzle_work_profile`、`custom_world_profile` 等源表后自行拼装列表；BFF 仍保留首屏、SEO / 分享、旧客户端、订阅失败和灰度期间的 HTTP fallback。
+统一公开作品 BFF 路由是 `GET /api/public-works` 与 `GET /api/public-works/{publicWorkCode}`，响应契约由 `shared-contracts::public_work` 和 `packages/shared/src/contracts/publicWork.ts` 共同维护。前端首期仍走 BFF HTTP，不直接订阅 SpacetimeDB；后续若允许浏览器直连订阅，也只能订阅 `public_work_gallery_entry` / `public_work_detail_entry` 这类稳定公开 read model，不能订阅 `puzzle_work_profile`、`custom_world_profile` 等源表后自行拼装列表。设计细节见 `docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。

 ### `quest_log`

@@ -704,7 +709,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - Rust view：`square_hole_gallery_view`
 - 返回类型：`Vec<SquareHoleGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/square_hole.rs`
- 说明：方洞挑战公开广场列表投影，只暴露 `publication_status = published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM square_hole_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'square-hole'` 后，从本地 cache 构造 `/api/runtime/square-hole/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_square_hole_works` procedure；个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
+- 说明：方洞挑战公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。

 ### `story_event`

@@ -779,4 +784,4 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - Rust view：`visual_novel_gallery_view`
 - 返回类型：`Vec<VisualNovelGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/visual_novel.rs`
- 说明：视觉小说公开广场列表投影，只暴露 `publication_status = published` 的作品卡片字段，不把完整 `draft` 暴露给公开列表订阅；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM visual_novel_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'visual-novel'` 后，从本地 cache 构造 `/api/runtime/visual-novel/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_visual_novel_works` procedure；个人历史、详情、运行态和发布仍按原有 procedure / reducer 路径处理。
+- 说明：视觉小说公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段，不把完整 `draft` 暴露给公开列表订阅；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人历史、详情、运行态和发布仍按原有 procedure / reducer 路径处理。
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -108,6 +108,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo.png` 卡通形象；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
 - 拼图运行态进行中关卡的 `elapsedMs` 仍是结算字段，设置面板的“当前用时”必须按 `startedAtMs`、暂停累计和冻结累计实时派生；不要直接把进行中的 `currentLevel.elapsedMs` 当作展示值。
 - 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden`，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
+- 推荐页嵌入拼图运行态时，“下一关”应优先切到相似作品；如果当前推荐候选为空，才回退到同作品下一关，避免匿名推荐流在多关卡作品上持续停留在同一作品内。下一关请求 pending 期间必须保留当前 `PuzzleRuntimeShell` 和棋盘，不得把推荐卡整体切回 `加载中...` 占位态；局部同步状态由拼图运行态自己的 busy 表现承接。后端返回的新关卡属于其它作品时，前端必须同步 `selectedPuzzleDetail`、推荐页 `puzzleGalleryEntries` 缓存和 `activeRecommendEntryKey`，让底部作品信息、分享 / 点赞 / 改造和下一次“下一个”基准都指向新作品。
 - 推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry`，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 `puzzleRun`。
 - 拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。