1

2026-04-29 11:51:04 +08:00
parent e191619ab3
commit 412279ae11
89 changed files with 3966 additions and 491 deletions
--- a/docs/design/PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md
+++ b/docs/design/PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md
@@ -0,0 +1,59 @@
+# 平台首页移动端信息流与作品卡设计
+
+更新时间：`2026-04-28`
+
+## 1. 本次目标
+
+1. 桌面端首页布局保持现有顶部栏、侧边导航、Hero、趋势区与下方网格结构，不调整桌面端区块顺序。
+2. 移动端首页改为参考图式信息流：顶部搜索框、横向频道 Tab、纵向作品列表、底部主导航。
+3. 双端公开作品卡统一结构：上方 `16:9` 封面图，下方作品名称、作品描述、标签、点赞数。
+4. 点赞数必须来自作品读模型字段，前端只负责展示，不把游玩数或评分临时改名成点赞。
+
+## 2. 数据契约
+
+### 2.1 统一字段
+
+公开作品卡和创作中心复用的作品摘要都增加：
+
+```ts
+likeCount: number
+```
+
+当前阶段只做只读展示，不新增点赞按钮和点击 reducer。后端对尚未接入真实点赞表的作品返回 `0`，保证接口 shape 稳定，后续可无 UI 结构迁移地接入真实互动计数。
+
+### 2.2 各玩法映射
+
+1. RPG 公开广场：`CustomWorldLibraryEntry` 与 `CustomWorldGalleryCard` 返回 `likeCount`，当前由 Rust facade 返回 `0`。
+2. 拼图公开广场：`PuzzleWorkSummary` 返回 `likeCount`，当前由 Rust facade 返回 `0`，`playCount` 继续仅表示游玩次数。
+3. 大鱼公开广场：`BigFishWorkSummary` 返回 `likeCount`，当前由 Rust facade 返回 `0`，`playCount` 继续仅表示游玩次数。
+4. 前端聚合类型 `PlatformPublicGalleryCard` 透传 `likeCount`，`WorldCard` 不再依赖 `badge/metaLabel` 决定主要信息结构。
+
+## 3. 移动端布局
+
+1. 移动端首页只在 `RpgEntryHomeView` 的 mobile content 内重排。
+2. 第一屏顺序：
+   - 搜索框
+   - 频道横滑 Tab：推荐、今日游戏、游戏分类、PC游戏、即点即玩
+   - 作品信息流
+3. 作品信息流使用单列纵向列表，卡片宽度填满容器，卡片之间保留短间距。
+4. 不新增功能说明类长文案；空态仍沿用现有短状态文案。
+5. 移动端卡片视觉允许接近参考图的深色信息流，但仍走平台主题 token，避免写死不可维护的大面积色块。
+
+## 4. 作品卡结构
+
+每张公开作品卡固定为：
+
+1. 封面区域：`aspect-ratio: 16 / 9`，图片 `object-cover`；无封面时使用轻量主题底。
+2. 信息区域：
+   - 第一行：作品名称，右侧点赞数。
+   - 第二行：作品描述，两行截断。
+   - 第三行：最多三个标签。
+3. 点赞数展示在参考图评分位置，使用心形图标 + 紧凑数字，例如 `128`、`1.2万`。
+4. 不展示作品号；作品号仍只在详情页或分享路径中使用。
+
+## 5. 验收
+
+1. 390px 移动端首页不横向溢出，能看到搜索、频道和纵向作品列表。
+2. 桌面端首页布局区块顺序不变，只替换公开作品卡内部结构。
+3. RPG、拼图、大鱼三类公开作品卡都有 `likeCount` 字段，前端聚合后能统一展示。
+4. 运行编码检查、前端定向测试和必要的 Rust 检查。
--- a/docs/design/PLATFORM_WORK_DETAIL_AND_REMIX_DESIGN_2026-04-28.md
+++ b/docs/design/PLATFORM_WORK_DETAIL_AND_REMIX_DESIGN_2026-04-28.md
@@ -0,0 +1,87 @@
+# 平台统一作品详情页与 Remix 数据链路设计
+
+更新时间：`2026-04-28`
+
+## 1. 本次目标
+
+1. 平台首页、公开广场、分类列表中的每个公开作品点击后，统一先进入作品详情页，不再直接启动玩法。
+2. 作品详情页结构参考 TapTap 详情页：顶部封面图、作品基础信息、右侧 Remix 按钮、四项统计、简介内容、底部启动按钮。
+3. 删除参考图顶部 Tab，不接入评价和论坛功能，不展示“开发者的话”模块。
+4. 统计数据必须从数据库读模型贯穿到前端展示，禁止在前端用假字段、游玩数冒充点赞数或固定文案代替真实字段。
+5. Remix 按钮必须由后端事务复制公开作品为当前用户草稿，并同步增加原作品改造次数，成功后前端进入新草稿详情/结果页。
+
+## 2. 详情页 UI 结构
+
+统一详情页只做作品展示与动作入口，不承担规则说明。
+
+1. 顶部导航：返回按钮、标题“详情”、更多按钮占位；不展示“统计 / 详情 / 评价 / 论坛”Tab。
+2. 封面区：使用作品封面图作为主视觉，背景可用同图弱化铺底；缺图时只显示平台主题底，不新增说明文字。
+3. 基础信息区：
+   - 左侧作品图标使用作品封面或首图。
+   - 中间展示作品名、作者名、玩法类型。
+   - 右侧原 TapTap 评分位置替换为 `Remix` 按钮。
+4. 统计区固定四项：
+   - 改造次数：`remixCount`
+   - 游玩次数：`playCount`
+   - 点赞次数：`likeCount`
+   - 上线日期：`publishedAt`
+5. 简介区：展示玩法标签和作品简介；不追加说明类文案。
+6. 底部动作：主按钮为“启动”，点击后进入对应玩法运行态并记录游玩次数。
+
+## 3. 数据真相源
+
+### 3.1 RPG 作品
+
+1. `custom_world_profile` 增加 `play_count`、`remix_count`、`like_count`。
+2. `custom_world_gallery_entry` 同步这三项统计，作为公开详情和首页卡片读模型。
+3. `record_custom_world_profile_play` 负责在公开作品启动前递增 `play_count`，只更新已发布且未删除作品。
+4. `remix_custom_world_profile` 在同一事务内：
+   - 校验源作品已发布、未删除。
+   - 递增源作品 `remix_count` 并刷新源作品 gallery。
+   - 复制源 profile payload 为当前用户草稿，清空公开编号、发布时间与统计。
+   - 返回新草稿 profile，供前端进入草稿详情页。
+
+### 3.2 拼图作品
+
+1. `puzzle_work_profile` 保留既有 `play_count`，新增 `remix_count`、`like_count`。
+2. `start_puzzle_run` 继续作为游玩次数递增入口。
+3. `remix_puzzle_work` 在同一事务内：
+   - 校验源 profile 为已发布作品。
+   - 递增源作品 `remix_count`。
+   - 新建当前用户拼图 Agent session，并把源作品锚点、封面、简介复制为草稿。
+   - 新建当前用户草稿 profile，统计归零，返回新草稿 session 与 profile。
+4. API facade 解析拼图 `item_json` / `items_json` 时必须兼容历史公开作品缺失 `play_count`、`remix_count`、`like_count` 的 JSON，缺失值统一按 `0` 处理；新写入数据仍必须写全统计字段。
+
+### 3.3 大鱼吃小鱼作品
+
+1. `big_fish_creation_session` 现有 `play_count` 继续作为游玩统计，新增 `remix_count`、`like_count`、`published_at`。
+2. `publish_big_fish_game` 写入 `published_at`，公开列表和详情用它展示上线日期。
+3. `record_big_fish_play` 继续作为游玩次数递增入口。
+4. `remix_big_fish_work` 在同一事务内：
+   - 校验源 session 为已发布作品。
+   - 递增源作品 `remix_count`。
+   - 新建当前用户创作 session，复制锚点、草稿和资源槽，阶段回到可编辑草稿态。
+   - 新 session 的统计归零，返回新草稿 session。
+
+## 4. API 与前端接入
+
+1. 三类公开作品摘要统一返回：`playCount`、`remixCount`、`likeCount`、`publishedAt`。
+2. Remix API：
+   - RPG：`POST /api/runtime/custom-world-gallery/{owner_user_id}/{profile_id}/remix`
+   - 拼图：`POST /api/runtime/puzzle/gallery/{profile_id}/remix`
+   - 大鱼：`POST /api/runtime/big-fish/gallery/{session_id}/remix`
+3. 前端统一详情页只消费读模型字段，不自行派生统计。
+4. 首页卡片点击只设置统一详情状态；启动与 Remix 只能在详情页触发。
+5. Remix 成功后的跳转：
+   - RPG：进入复制出的草稿详情。
+   - 拼图：进入复制出的拼图结果页草稿。
+   - 大鱼：进入复制出的大鱼结果页草稿。
+
+## 5. 验收点
+
+1. 三类作品从首页点击均先进入统一作品详情页。
+2. 详情页无评价、论坛 Tab，无开发者的话模块。
+3. 四项统计在前端、共享契约、API facade、SpacetimeDB 表之间字段一致。
+4. Remix 后原作品改造次数增加，新草稿归当前用户所有，且不会继承源作品统计。
+5. 启动公开作品会走对应后端记录入口，刷新后仍能看到递增后的游玩次数。
+6. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。
--- a/docs/design/README.md
+++ b/docs/design/README.md
@@ -10,6 +10,7 @@
 - [CUSTOM_WORLD_TEMPLATE_DECOUPLING_AND_CROSS_GENRE_GENERALIZATION_DESIGN_2026-04-08.md](./CUSTOM_WORLD_TEMPLATE_DECOUPLING_AND_CROSS_GENRE_GENERALIZATION_DESIGN_2026-04-08.md)：把自定义世界从武侠/仙侠模板依赖迁到跨题材通用设定层的优化设计。
 - [CUSTOM_WORLD_SELF_OWNED_SETTING_LAYER_OPTIMIZATION_2026-04-08.md](./CUSTOM_WORLD_SELF_OWNED_SETTING_LAYER_OPTIMIZATION_2026-04-08.md)：把模板依赖逐步迁成自定义世界自有设定层，并保证不破坏当前生成流程的优化方案。
 - [MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md](./MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md)：移动端创作页新建作品模块最多占用首屏约 1/3 高度的紧凑布局设计。
+- [PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md](./PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md)：平台首页移动端参考图式信息流、双端公开作品卡 16:9 封面结构与点赞数读模型设计。
 - [PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md](./PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md)：平台入口新增分类 Tab、登录态导航裁剪与创作 Tab 视觉强化设计。
 - [PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md](./PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md)：平台入口暂时隐藏大鱼吃小鱼创作卡片，但保留现有玩法链路。
 - [UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md](./UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md)：统一平台风与 RPG 像素风模态窗口外壳、交互边界和迁移顺序。
--- a/docs/technical/FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md
+++ b/docs/technical/FRONTEND_INDEPENDENT_PAGE_ROUTES_2026-04-25.md
@@ -16,22 +16,23 @@

 ## 页面路径表

-| 页面阶段 | 路径 | 说明 |
-| --- | --- | --- |
-| `platform` | `/` | 平台首页、广场、我的、创作中心等主入口 |
-| `detail` | `/worlds/detail` | RPG 世界详情页，依赖当前已选作品 |
-| `agent-workspace` | `/creation/rpg/agent` | RPG Agent 共创工作区 |
-| `custom-world-generating` | `/creation/rpg/generating` | RPG 世界草稿生成进度页 |
-| `custom-world-result` | `/creation/rpg/result` | RPG 世界结果页与编辑页 |
-| `big-fish-agent-workspace` | `/creation/big-fish/agent` | 大鱼吃小鱼 Agent 共创工作区 |
-| `big-fish-result` | `/creation/big-fish/result` | 大鱼吃小鱼草稿结果页 |
-| `big-fish-runtime` | `/runtime/big-fish` | 正式链路中的大鱼吃小鱼运行页 |
-| `puzzle-agent-workspace` | `/creation/puzzle/agent` | 拼图 Agent 共创工作区 |
-| `puzzle-result` | `/creation/puzzle/result` | 拼图草稿结果页 |
-| `puzzle-gallery-detail` | `/gallery/puzzle/detail` | 拼图作品详情页，依赖当前已选作品 |
-| `puzzle-runtime` | `/runtime/puzzle` | 正式链路中的拼图运行页 |
-| RPG 选角页 | `/runtime/rpg/characters` | 进入世界后、确认角色前的选角阶段 |
-| RPG 冒险页 | `/runtime/rpg/adventure` | 已确认角色后的 RPG 主运行态 |
+| 页面阶段                   | 路径                        | 说明                                                   |
+| -------------------------- | --------------------------- | ------------------------------------------------------ |
+| `platform`                 | `/`                         | 平台首页、广场、我的、创作中心等主入口                 |
+| `work-detail`              | `/works/detail`             | 统一公开作品详情页，承接 RPG、拼图、大鱼吃小鱼公开作品 |
+| `detail`                   | `/worlds/detail`            | RPG 世界详情页，依赖当前已选作品                       |
+| `agent-workspace`          | `/creation/rpg/agent`       | RPG Agent 共创工作区                                   |
+| `custom-world-generating`  | `/creation/rpg/generating`  | RPG 世界草稿生成进度页                                 |
+| `custom-world-result`      | `/creation/rpg/result`      | RPG 世界结果页与编辑页                                 |
+| `big-fish-agent-workspace` | `/creation/big-fish/agent`  | 大鱼吃小鱼 Agent 共创工作区                            |
+| `big-fish-result`          | `/creation/big-fish/result` | 大鱼吃小鱼草稿结果页                                   |
+| `big-fish-runtime`         | `/runtime/big-fish`         | 正式链路中的大鱼吃小鱼运行页                           |
+| `puzzle-agent-workspace`   | `/creation/puzzle/agent`    | 拼图 Agent 共创工作区                                  |
+| `puzzle-result`            | `/creation/puzzle/result`   | 拼图草稿结果页                                         |
+| `puzzle-gallery-detail`    | `/gallery/puzzle/detail`    | 拼图作品详情页，依赖当前已选作品                       |
+| `puzzle-runtime`           | `/runtime/puzzle`           | 正式链路中的拼图运行页                                 |
+| RPG 选角页                 | `/runtime/rpg/characters`   | 进入世界后、确认角色前的选角阶段                       |
+| RPG 冒险页                 | `/runtime/rpg/adventure`    | 已确认角色后的 RPG 主运行态                            |

 ## 落地边界

--- a/docs/technical/PUBLIC_WORK_CODE_MOBILE_SHARE_ENTRY_FIX_2026-04-25.md
+++ b/docs/technical/PUBLIC_WORK_CODE_MOBILE_SHARE_ENTRY_FIX_2026-04-25.md
@@ -16,7 +16,7 @@

 ## 作品分享路由补充

-1. 公开作品入口路由统一使用当前作品页面路径加 `work=作品号`：RPG 为 `/worlds/detail?work=CW-00000001`，拼图为 `/gallery/puzzle/detail?work=PZ-00000001`，大鱼玩法为 `/runtime/big-fish?work=BF-00000001`。
+1. 公开作品入口路由统一使用 `/works/detail?work=作品号`，三类作品在该页先展示统一公开详情，再由“启动”进入对应运行态；旧 `/worlds/detail` 与 `/gallery/puzzle/detail` 只保留给既有创作/编辑链路。
 2. 从公开广场、最近浏览、创作中心打开已发布作品详情或玩法时，若当前作品有公开作品号，地址栏必须同步追加 `work=作品号`；没有作品号的草稿详情仍保持无查询参数路径。
 3. 首次进入主应用时若 URL 带 `work` 查询参数，平台入口自动复用现有公开编号搜索逻辑打开对应作品详情，不新增独立详情系统。
 4. 详情页必须保留“复制作品号”和“分享作品”两个独立动作：
@@ -34,5 +34,5 @@
 5. 桌面右侧趋势列表只显示排序和作品类型，不再显示 `1777110165.990127Z` 这类原始时间字符串，也不直接显示作品号。
 6. 在内嵌浏览器 Clipboard API 拒绝写入时，详情页与创作中心作品号复制仍能通过降级路径完成，并显示 `已复制` 或 `复制失败`。
 7. 打开拼图详情后点击返回，不再固定跳到创作中心，而是回到打开详情前的平台 Tab。
-8. 打开 `/?work=CW-00000001`、`/worlds/detail?work=CW-00000001`、`/gallery/puzzle/detail?work=PZ-00000001` 或 `/runtime/big-fish?work=BF-00000001` 后能自动进入对应公开作品详情或玩法。
+8. 打开 `/?work=CW-00000001` 或 `/works/detail?work=CW-00000001` 后能自动进入对应公开作品详情；拼图、大鱼吃小鱼作品号同样进入统一公开详情后再启动玩法。
 9. 点击详情页“分享作品”后，剪切板内容包含邀请文本、作品号和当前站点下带 `work=作品号` 的完整网址。
--- a/docs/technical/RPG_NPC_CHAT_TRANSIENT_SNAPSHOT_SESSION_FIX_2026-04-28.md
+++ b/docs/technical/RPG_NPC_CHAT_TRANSIENT_SNAPSHOT_SESSION_FIX_2026-04-28.md
@@ -0,0 +1,49 @@
+# RPG NPC 聊天禁存快照会话修复（2026-04-28）
+
+## 背景
+
+复测 NPC 对话时，前端请求：
+
+```text
+POST /api/runtime/chat/npc/turn/stream
+```
+
+返回 `409 Conflict`，错误为：
+
+```text
+请求的运行时会话与服务端快照不一致，请重新进入游戏
+```
+
+当前 story action 主链已经支持 `runtimePersistenceDisabled = true` 的运行态：这类请求会携带临时 `snapshot`，后端只构造本次响应，不写入 `runtime_snapshot`。但 NPC 聊天接口在带 `sessionId` 时只从正式 `runtime_snapshot` 读取上下文。若当前运行态是作品测试、幕预览或其他禁存 run，服务端正式快照仍可能是上一局正式存档，导致 `sessionId` 与 `snapshotSessionId` 不一致。
+
+## 修复原则
+
+1. 正式 `play` 且允许持久化的运行态，聊天请求继续只提交 `sessionId` 与聊天输入，保持后端快照为唯一来源。
+2. `runtimePersistenceDisabled = true` 或历史 `runtimeMode = preview/test` 的运行态，聊天请求必须携带临时 `snapshot`。
+3. 后端聊天接口收到临时 `snapshot` 时，只用它投影本轮 prompt context、NPC state、history、encounter，不写入 `runtime_snapshot`。
+4. 临时 `snapshot.gameState.runtimeSessionId` 必须与请求 `sessionId` 一致；不一致仍返回 `409`。
+5. 前端不得把完整快照默认用于正式游玩聊天，避免重新扩大浏览器对正式真相链的写入权。
+
+## 工程落点
+
+1. `packages/shared/src/contracts/rpgRuntimeChat.ts`
+   - 给角色聊天、NPC 对话、NPC 单轮、招募对话请求补可选 `snapshot` 字段。
+2. `src/services/aiService.ts`
+   - 增加禁存运行态 snapshot 构造。
+   - 仅在 `context.runtimeSnapshot` 存在时，随聊天请求提交 `snapshot`。
+3. `src/services/aiTypes.ts`
+   - `StoryGenerationContext` 增加可选 `runtimeSnapshot`。
+4. `src/hooks/rpg-runtime-story/storyContextBuilder.ts`
+   - 禁存运行态把当前 `GameState` 作为临时 snapshot 注入 context。
+5. `server-rs/crates/api-server/src/runtime_chat.rs`
+   - `NpcChatTurnRequest` 接收 `snapshot`。
+   - 优先使用请求 snapshot 校验并投影上下文。
+6. `server-rs/crates/api-server/src/runtime_chat_plain.rs`
+   - 角色聊天、NPC 开场、招募同样支持临时 snapshot。
+
+## 验收
+
+1. 禁存运行态 NPC 聊天请求体携带 `snapshot`，正式运行态不携带。
+2. 后端 NPC 聊天在请求 snapshot 与正式存档 session 不一致时，仍按请求 snapshot 成功投影，不读取旧正式存档。
+3. snapshot 内部 `runtimeSessionId` 与请求 `sessionId` 不一致时返回 `409`。
+4. 相关前端单测、后端 `runtime_chat` 单测、编码检查通过。