1

docs/prd/AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md

@@ -89,17 +89,17 @@
    - 合并块整体拖动
    - 单块拖到合并块位置时拆分合并块
 10. 游戏画面必须显示作者信息和关卡名。
-11. 前端只负责表现和交互输入，逻辑、数据、关卡裁决、推荐计算、状态存储全部放到 `server-rs` 后端，由 `Axum + SpacetimeDB + OSS` 方案承接。
+11. 拼块交换、拖动、合并、拆分和本关通关判定由前端即时裁决；`server-rs` 继续承接素材、开局、下一关推荐、扣费、排行榜和跨端服务侧状态。
 
-### 第一版单机例外说明 2026-04-24
+### 运行态前端裁决说明 2026-04-29
 
-为了先把拼图玩法跑通，第一版运行态采用单机本地版本，作为上面总原则的阶段性例外：
+为了保证拖动手感和正式链路玩法一致，拼图运行态采用前端即时裁决：
 
 1. Agent 会话、结果页草稿、正式候选图生成、封面确认、发布、作品读取，仍然全部走 Rust 后端。
-2. 进入拼图玩法后的 `run` 只在前端本地内存中存在。
-3. 交换、拖动、通关判断不写回后端。
-4. 关闭玩法后不保留本次运行态，不做断点续玩。
-5. 后续如果要做跨端续玩、多端同步或排行榜，再把运行态真相源收回后端。
+2. 进入拼图玩法后，拼块布局、合并组、拆分结果和本关通关状态由前端基于当前 `PuzzleRunSnapshot` 计算。
+3. 交换、拖动、合并、拆分、通关判断不写回后端。
+4. 正式 run 的下一关推荐、道具扣费、暂停计时同步、排行榜提交继续走后端。
+5. 后续如果要做跨端续玩或多端同步，必须先更新本文档，再决定哪些运行态真相源收回后端。
 
 ---
 
@@ -114,7 +114,7 @@
 5. 不做复杂剧情文本或玩法说明文本默认堆在 UI 中。
 6. 不做独立于平台创作中心之外的新创作站点。
 7. 不做前端本地计算下一关推荐结果。
-8. 不做前端本地裁决拼块合并、拆分和关卡完成。
+8. 不做前端本地计算下一关推荐、扣费或排行榜；拼块交换、拖动、合并、拆分和本关通关判定由前端即时裁决。
 9. 不把拼图玩法继续命名挂在 `customWorld` 或 `rpgWorld` 老前缀下。
 
 ---
@@ -374,8 +374,8 @@ interface PuzzleAnchorPack {
 
 拼图图片的正式资产要求：
 
-1. 官方拼图原图统一使用 `9:16` 竖屏比例。
-2. 建议第一版正式生成尺寸为 `720 x 1280`。
+1. 官方拼图原图统一使用 `1:1` 正方形比例。
+2. 建议第一版正式生成尺寸为 `1024 x 1024`。
 3. 图中不允许生成标题字、水印、边框、按钮或 UI。
 4. 图像主体必须足够清晰，切成 `4*4` 后仍然有辨识信息。
 
@@ -502,7 +502,7 @@ tagSimilarityScore =
 画面要求：
 
 1. 拼图舞台占满可用全屏区域
-2. 真正可操作的拼图棋盘按 `9:16` 竖屏比例填满安全区域
+2. 真正可操作的拼图棋盘按正方形比例填满安全区域，并在移动端贴近屏幕两侧边缘
 3. 棋盘外延空间用同图模糊背景或纯净氛围底承接
 4. 不默认堆玩法说明文字
 
@@ -625,7 +625,7 @@ V1 规则如下：
 
 ## 9.11 重算范围
 
-为了避免前端和后端做整盘重复计算，每次操作后只重算受影响区域：
+为了避免前端每次操作后做整盘重复计算，只重算受影响区域：
 
 1. 本次发生交换的源格子
 2. 本次发生交换的目标格子
@@ -639,7 +639,7 @@ V1 规则如下：
 1. 所有拼块合并成 `1` 个覆盖全盘的大合并块
 2. 所有拼块都回到原始正确位置
 
-在正式实现中，建议以后端 `allTilesResolved = true` 作为唯一真相。
+在正式实现中，前端以本地计算得到的 `allTilesResolved = true` 或关卡 `status = cleared` 作为本关通关真相；后端不再参与拼块布局裁决。
 
 ## 9.13 限时与失败
 
@@ -755,17 +755,17 @@ interface PuzzleRunSnapshot {
 1. 展示 Agent 聊天界面
 2. 展示结果页
 3. 展示拼图画布、选中态、拖动反馈、合并反馈
-4. 发起交换、拖动、发布、开始游戏等请求
+4. 即时裁决拼块交换、拖动、合并、拆分和本关通关状态
+5. 发起发布、开始游戏、下一关、道具、排行榜等请求
 
 前端不负责：
 
 1. 解析锚点完成度
 2. 计算推荐下一关
 3. 计算标签相似度
-4. 判定哪些块应该合并
-5. 判定合并块何时拆分
-6. 判定通关
-7. 保存 run 状态
+4. 计算下一关推荐
+5. 保存跨端 run 状态
+6. 执行道具扣费或排行榜写入
 
 ## 11.2 后端职责
 
@@ -777,10 +777,9 @@ interface PuzzleRunSnapshot {
 4. 发布作品到拼图广场
 5. 创建 run
 6. 初始化关卡棋盘
-7. 裁决交换、合并、拆分、拖动结果
-8. 判定通关
-9. 计算下一关推荐
-10. 保存当前 run 快照
+7. 计算下一关推荐
+8. 保存当前 run 的关卡入口、计时、道具和排行榜相关状态
+9. 兼容保留旧交换接口；拖动接口不作为 Rust API 默认能力暴露，前端不依赖后端裁决拼块布局
 
 ---
 
@@ -797,11 +796,12 @@ interface PuzzleRunSnapshot {
    - 结果页交互
    - 拼图画布渲染
    - HUD、选中态、拖动态、合并反馈表现
+   - 拼块交换、拖动、合并、拆分与本关通关判定
 3. 前端不得承担：
    - 推荐算法
-   - run 状态持久化
-   - 拼块合并与拆分裁决
-   - 通关判定
+   - run 状态跨端持久化
+   - 道具扣费
+   - 排行榜写入
 4. 若后续拼图运行时需要实时订阅或读取 `SpacetimeDB` 数据，前端接入必须显式以 `spacetimedb-typescript` 约束为准。
 
 ### HTTP 与外部副作用层
@@ -818,15 +818,16 @@ interface PuzzleRunSnapshot {
 
 ### 状态真相源
 
-1. 拼图玩法的运行时状态、作品状态、Agent 会话状态、广场投影状态，统一以 `SpacetimeDB` 为唯一真相源。
-2. `SpacetimeDB` 中应承担：
+1. 拼图玩法的作品状态、Agent 会话状态、广场投影状态、下一关推荐、道具扣费和排行榜等服务侧状态，统一以 `SpacetimeDB` 为唯一真相源。
+2. 当前关卡的拼块布局、合并组、拆分结果和本关通关状态，运行中以前端即时计算结果为准，不要求每一步写回 `SpacetimeDB`。
+3. `SpacetimeDB` 中应承担：
    - 拼图作品 profile 表
    - 拼图 Agent session / message / operation 表
-   - 拼图 run 与关卡状态表
-   - 拼块与合并组状态表
+   - 拼图 run 入口、关卡服务状态与排行榜表
+   - 下一关候选、道具扣费和榜单聚合所需状态
    - 拼图广场投影表
    - 标签相似度计算所需的规范化标签字段
-3. 所有真正修改状态的行为必须通过 reducer 或 procedure 完成，不能由 Axum 或前端偷偷改状态。
+4. 所有服务侧状态修改必须通过 reducer 或 procedure 完成，不能由 Axum 或前端偷偷改服务侧状态。
 
 ### 资产存储
 
@@ -1036,9 +1037,12 @@ interface PuzzleRunSnapshot {
 
 1. `POST /api/runtime/puzzle-runtime/runs`
 2. `GET /api/runtime/puzzle-runtime/runs/:runId`
-3. `POST /api/runtime/puzzle-runtime/runs/:runId/swap`
-4. `POST /api/runtime/puzzle-runtime/runs/:runId/drag`
-5. `POST /api/runtime/puzzle-runtime/runs/:runId/next-level`
+3. `POST /api/runtime/puzzle-runtime/runs/:runId/next-level`
+4. `POST /api/runtime/puzzle-runtime/runs/:runId/pause`
+5. `POST /api/runtime/puzzle-runtime/runs/:runId/props`
+6. `POST /api/runtime/puzzle-runtime/runs/:runId/leaderboard`
+
+`swap` 兼容接口可以保留，但前端默认不再调用；`drag` 不作为默认 HTTP 入口暴露。拼块布局由前端即时裁决。
 
 ---
 
@@ -1084,7 +1088,7 @@ interface PuzzleRunSnapshot {
 建议布局：
 
 1. 顶部轻量 HUD
-2. 中间 `9:16` 竖屏拼图棋盘
+2. 中间正方形拼图棋盘，移动端贴近屏幕两侧边缘
 3. 底部不常驻大段文案
 
 如需操作提示，只允许短暂轻提示，不允许占据长期版面。