Genarrative/docs/design/PLATFORM_WORK_DETAIL_AND_REMIX_DESIGN_2026-04-28.md

平台统一作品详情页与 Remix 数据链路设计

更新时间：2026-05-01

1. 本次目标

1. 平台首页、公开广场、分类列表中的每个公开作品点击后，统一先进入作品详情页，不再直接启动玩法。
2. 作品详情页结构参考 TapTap 详情页：顶部封面图、作品基础信息、右侧“点赞”按钮、四项统计、简介内容、底部“作品改造 + 启动”同行动作。
3. 删除参考图顶部 Tab，不接入评价和论坛功能，不展示“开发者的话”模块。
4. 统计数据必须从数据库读模型贯穿到前端展示，禁止在前端用假字段、游玩数冒充点赞数或固定文案代替真实字段。
5. Remix 按钮必须由后端事务复制公开作品为当前用户草稿，并同步增加原作品改造次数，成功后前端进入新草稿详情/结果页。

2. 详情页 UI 结构

统一详情页只做作品展示与动作入口，不承担规则说明。

1. 顶部导航：返回按钮、标题“详情”、更多按钮占位；不展示“统计 / 详情 / 评价 / 论坛”Tab。
2. 封面区：固定 16:9 比例，默认使用作品封面图 cover 填满整块主视觉；背景可用同图弱化铺底；缺图时只显示平台主题底，不新增说明文字。拼图作品详情页若详情数据包含多个关卡图，则顶部封面区优先按关卡正式图轮播展示，每张图对应一个关卡；无可用关卡图时再回退作品封面图。拼图多关封面只默认展示第一张真实图，轮播节奏与左右切换保持不变；未解锁的后续封面必须使用同图毛玻璃模糊底和大问号图标遮罩，不能展示真实清晰图，也不能追加规则说明文字。玩家完成对应前置关卡后，当前详情页可按本次 PuzzleRunSnapshot.clearedLevelCount + 1 即时解锁可见封面数；刷新后持久化解锁应由后端从当前用户的拼图运行记录汇总到详情读模型，前端只消费读模型或当前 run 状态。
3. 移动端首页“推荐”和“今日游戏”列表中，只有最接近屏幕垂直中心的作品卡片进入封面轮播态；若该拼图作品有多张关卡封面，则按详情页同源封面序列自动轮换。用户滚动后，离开中心的旧卡片必须立即恢复首张封面，新中心卡片再开始轮播；“游戏分类”、排行、桌面端列表不启用该自动轮播。
4. 基础信息区：
   • 左侧作品图标使用作品封面序列首图；顶部封面轮播切换时，该正方形图标保持首图不变，避免作品名称旁的身份标识跟随大图闪动。
   • 中间展示作品名、作者头像、作者名、玩法类型；作者头像读取公开用户资料 avatarUrl，缺失时使用作者昵称首字占位。
   • 右侧原 TapTap 评分位置替换为 点赞 按钮；点击后调用后端点赞接口，由后端记录当前登录用户对该公开作品的点赞关系并返回更新后的真实 likeCount 读模型，前端不伪造点赞增长。
5. 统计区固定四项：
   • 游玩：playCount，显示为“数字 + 次”，单位放在数字后方。
   • 改造：remixCount，显示为“数字 + 次”，单位放在数字后方。
   • 点赞：likeCount，显示为“数字 + 赞”，单位放在数字后方。
   • 日期：优先展示 updatedAt，缺失时回退 publishedAt；前端只负责格式化显示，必须兼容后端当前 seconds.microsZ 与 ISO 字符串两种真实时间文本，显示为完整 YYYY-MM-DD，使用更小字号并保持单行不换行。
   • 四项统计需要使用浅色图标底强化识别，但不得追加规则说明类文案。
6. 简介区：展示玩法标签和作品简介；不追加说明类文案。
7. 底部动作：左侧按钮为“作品改造”，右侧主按钮为“启动”；两个按钮必须位于同一行，点击“启动”后进入对应玩法运行态并记录游玩次数。
   • 未登录用户可进入并浏览作品详情页，但点击“作品改造”和“启动”都必须先弹出登录入口面板；登录成功后自动继续刚才点击的动作，不直接发起 Remix、启动 run 或本地运行态。
8. 页面配色必须跟随平台明暗主题变量；亮色主题使用平台浅色底、深色文字和主按钮渐变，暗色主题使用平台暗色底、亮色文字和对应主按钮渐变，不在详情页写死独立黑色皮肤。
9. 字号规范跟随平台页面既有节奏：标题/主按钮使用 1rem 级别，作品名使用卡片标题同级 1rem，辅助信息与简介使用 0.8125rem / 0.875rem，标签与统计标签使用 0.75rem，避免在详情页使用随视口放大的独立大字号。

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. record_custom_world_profile_like 负责记录当前用户对公开作品的点赞；同一用户对同一公开作品只计入一次，首次点赞时递增 like_count 并同步刷新 custom_world_gallery_entry。
5. 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. record_puzzle_work_like 负责记录当前用户对公开拼图作品的点赞；同一用户对同一公开作品只计入一次，首次点赞时递增 like_count。
4. remix_puzzle_work 在同一事务内：
   • 校验源 profile 为已发布作品。
   • 递增源作品 remix_count。
   • 新建当前用户拼图 Agent session，并把源作品锚点、封面、简介复制为草稿。
   • 新建当前用户草稿 profile，统计归零，返回新草稿 session 与 profile。
5. 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 与 updated_at，公开列表和详情优先用 updated_at 展示最近更新。
3. record_big_fish_play 继续作为游玩次数递增入口。
4. record_big_fish_like 负责记录当前用户对公开大鱼作品的点赞；同一用户对同一公开作品只计入一次，首次点赞时递增 like_count。
5. remix_big_fish_work 在同一事务内：
   • 校验源 session 为已发布作品。
   • 递增源作品 remix_count。
   • 新建当前用户创作 session，复制锚点、草稿和资源槽，阶段回到可编辑草稿态。
   • 新 session 的统计归零，返回新草稿 session。

4. API 与前端接入

1. 三类公开作品摘要统一返回：playCount、remixCount、likeCount、publishedAt、updatedAt。
   • 作者头像不固化到作品读模型；详情页按 authorPublicUserCode 或 ownerUserId 读取公开用户摘要中的 avatarUrl，确保头像跟随账号资料更新。
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. 点赞 API：
   • RPG：POST /api/runtime/custom-world-gallery/{owner_user_id}/{profile_id}/like
   • 拼图：POST /api/runtime/puzzle/gallery/{profile_id}/like
   • 大鱼：POST /api/runtime/big-fish/gallery/{session_id}/like
   • 三个接口都必须走登录态鉴权，后端使用当前登录用户身份写入点赞关系；重复点击返回当前最新读模型，不重复增加 likeCount。
4. 前端统一详情页只消费读模型字段，不自行派生统计。
5. 首页卡片点击只设置统一详情状态；启动、点赞与 Remix 只能在详情页触发。
6. Remix 成功后的跳转：
   • RPG：进入复制出的草稿详情。
   • 拼图：进入复制出的拼图结果页草稿。
   • 大鱼：进入复制出的大鱼结果页草稿。
7. 拼图作品详情页启动时复用当前详情页已经展示的公开作品读模型，直接调用 POST /api/runtime/puzzle/runs 记录游玩并进入运行态；不得在启动前额外依赖 GET /api/runtime/puzzle/gallery/{profile_id}，避免开发代理或详情读取短断点阻塞启动链路。
8. 本地开发时 localhost:3000 是 Vite 前端端口，/api/** 默认代理到 Rust api-server:3100；若 3100 未监听，点击启动、点赞或作品改造会在浏览器显示 /api/... 500，此时真实断点是 Rust 后端未启动，不允许用前端假数据替代后端事务。

5. 验收点

1. 三类作品从首页点击均先进入统一作品详情页。
2. 详情页无评价、论坛 Tab，无开发者的话模块。
3. 四项统计在前端、共享契约、API facade、SpacetimeDB 表之间字段一致。
4. Remix 后原作品改造次数增加，新草稿归当前用户所有，且不会继承源作品统计。
5. 点赞公开作品会走对应后端记录入口，首次点赞后刷新仍能看到递增后的点赞次数，重复点赞不会继续增加。
6. 启动公开作品会走对应后端记录入口，刷新后仍能看到递增后的游玩次数。
7. 未登录进入作品详情页后，点击“作品改造”和“启动”只打开登录入口面板；登录成功后恢复对应动作，未登录期间不会创建 Remix 草稿、开始拼图 run、记录 RPG 游玩或启动大鱼本地运行态。
8. 移动端首页“推荐”和“今日游戏”列表滚动时，仅中心卡片自动轮播多封面；旧中心卡离开后回到首张封面，新的中心卡接续轮播。
9. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。