1

docs/technical/PUZZLE_FAILURE_EXTENSION_AND_SAVE_ARCHIVE_2026-05-01.md

@@ -57,13 +57,13 @@
 1. `world_key = puzzle:{entry_profile_id}`。
 2. `world_type = PUZZLE`。
 3. `profile_id = entry_profile_id`，保证同一个作品链只覆盖一条存档。
-4. `world_name` 使用当前关卡名。
+4. `world_name` 使用当前可恢复关卡名。
 5. `subtitle` 使用 `第 N 关`。
-6. `summary_text` 使用当前状态：
+6. `summary_text` 使用可恢复关卡状态：
    - playing：`拼图进行中`
    - failed：`关卡失败`
    - cleared：`关卡已完成`
-7. `cover_image_src` 使用当前关卡正式图。
+7. `cover_image_src` 使用可恢复关卡正式图。
 8. `game_state_json` 保存最小拼图恢复载荷：
    - `runtimeKind = "puzzle"`
    - `runId`
@@ -73,6 +73,8 @@
    - `currentLevelId`
    - `status`
 
+通关存档投影有一个额外规则：如果当前关卡已通关，并且 `refresh_next_level_handoff` 已经确认同作品存在下一关，则存档立即投影到同作品下一关入口，`status` 写为 `playing`，`subtitle / world_name / cover_image_src / currentLevelId` 都使用下一关。若当前作品没有下一关、只存在相似作品候选，存档保持当前已通关关卡，等待玩家在结算弹窗里选择相似作品，不能提前替玩家切换到某个候选作品。
+
 ## 写入时机
 
 SpacetimeDB 拼图运行态每次持久化 run 时同步刷新存档：
@@ -81,8 +83,9 @@ SpacetimeDB 拼图运行态每次持久化 run 时同步刷新存档：
 2. `advance_puzzle_next_level`：进入下一关后更新同一条存档。
 3. `use_puzzle_runtime_prop(extendTime)`：续时成功后更新状态。
 4. `get_puzzle_run` 导致失败态落库时，也同步更新为失败存档。
+5. `submit_puzzle_leaderboard_entry`：正式 run 提交成绩并把当前关标记为已通关时，先刷新下一关 handoff，再按上面的通关投影规则同步存档。
 
-排行榜提交只负责成绩与通关态，不新增存档规则；如果它把 run 状态更新为通关，也跟随 run 持久化刷新存档。
+前端在 `startPuzzleRun / usePuzzleProp / submitPuzzleLeaderboard / advancePuzzleLevel / getPuzzleRun` 成功后主动刷新存档列表，避免存档页停留在进入作品前或上一关的旧投影。
 
 ## 验收
 
@@ -91,5 +94,5 @@ SpacetimeDB 拼图运行态每次持久化 run 时同步刷新存档：
 3. 陶泥币余额不足时确认弹窗保留，并展示错误。
 4. 点击 `重新开始` 后当前关卡重新打乱并重置倒计时。
 5. 进入拼图作品后，存档页出现 `worldType = PUZZLE` 的拼图存档。
-6. 通过一关进入下一关后，同一条存档更新到新关卡。
+6. 通过一关后，只要后端确认同作品下一关存在，同一条存档立即更新到新关卡；没有同作品下一关时保留已完成关卡，等待玩家选择相似作品。
 7. 定向前端测试、Rust 拼图模块测试与编码检查通过。

docs/technical/PUZZLE_WORK_POINT_INCENTIVE_2026-05-01.md

@@ -46,7 +46,7 @@
    - `POST /api/runtime/puzzle/works/{profile_id}/point-incentive/claim`
    - 返回更新后的 `PuzzleWorkProfile`。
 3. 创作页仅对已发布拼图作品显示积分激励块；RPG、大鱼和草稿卡不显示。
-4. 领取成功后刷新对应拼图作品列表状态，按钮立即禁用或显示新的待领取数。
+4. 领取成功后刷新对应拼图作品列表状态，按钮立即禁用或显示新的待领取数，并同步刷新个人钱包看板。
 5. `spacetime-client` 映射层继续兼容历史拼图运行快照：旧 `run_json` 若缺少 `started_at_ms`，API 记录回填为非 0 值，避免前端计时器拿到无效开始时间。
 
 ## 5. 验收点
@@ -56,4 +56,5 @@
 3. 待领取积分为 0 时领取按钮禁用。
 4. 非作者游玩他人拼图并使用付费道具后，该作品累计 half points 增加。
 5. 作者领取后钱包增加向下取整后的整数陶泥币，作品待领取数归零或保留不足 1 的小数余额。
-6. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。
+6. 领取成功后顶部/我的页钱包余额随个人看板刷新。
+7. 修改后运行编码检查、SpacetimeDB 绑定生成、Rust 检查和必要前端测试。