1

docs/technical/PUZZLE_FAILURE_EXTENSION_AND_SAVE_ARCHIVE_2026-05-01.md

@@ -0,0 +1,95 @@
+# 拼图失败续时与存档投影设计 2026-05-01
+
+## 背景
+
+拼图运行时已经有倒计时失败态、道具确认扣费、下一关推荐和个人存档页，但失败后的玩家选择与拼图作品存档投影还没有闭环：
+
+1. 倒计时结束后只能返回，不能重新开始或付费继续。
+2. 进入拼图作品后，存档页没有稳定出现一条可恢复的拼图游戏存档。
+3. 每通过一关后，存档应该更新到下一关入口，而不是停留在旧关卡。
+
+本轮只补齐拼图运行态与存档投影，不迁移旧 `server-node`，不新增平行存档页。
+
+## 目标
+
+1. 限定时间内未完成时弹出失败面板。
+2. 失败面板提供两个选择：
+   - `重新开始`：重新开启当前拼图关卡，不扣陶泥币。
+   - `继续1分钟`：先弹出确认窗口，确认后消耗 `1` 陶泥币，并把当前失败关卡恢复为 `playing`，剩余时间固定为 `60000ms`。
+3. 进入拼图作品后立即写入 `profile_save_archive`，存档页显示拼图存档。
+4. 每次进入下一关后更新同一条拼图存档，使存档恢复时指向最新可继续的关卡。
+
+## 运行态规则
+
+### 失败续时
+
+`PuzzleRuntimePropKind` 增加 `extendTime`，沿用现有道具确认与扣费接口：
+
+1. 前端只在 `runtimeStatus = failed` 时开放 `继续1分钟`。
+2. 点击后打开独立确认弹窗，文案只显示短标题和 `消耗 1 陶泥币`。
+3. 正式 run 继续走 `POST /api/runtime/puzzle/runs/:runId/props`。
+4. `api-server` 将 `extendTime` 映射为账单 `asset_kind = puzzle_prop_extend_time`。
+5. SpacetimeDB 侧只允许失败关卡续时；续时成功后：
+   - `status = playing`
+   - `remaining_ms = 60000`
+   - `elapsed_ms = None`
+   - `cleared_at_ms = None`
+   - 清空暂停与冻结生效点
+   - 调整 `paused_accumulated_ms`，保证从确认成功那一刻开始完整倒计时 `60` 秒
+
+本地调试 run 没有真实钱包，沿用本地道具兜底：仍弹确认窗，但不扣真实陶泥币。
+
+### 重新开始
+
+重新开始不复用旧失败棋盘，而是重新创建当前关卡的 run：
+
+1. 前端从当前 `currentLevel.profileId` 和 `currentLevel.levelId` 调用 `startPuzzleRun`。
+2. 新 run 的棋盘重新打乱、倒计时重置。
+3. 如果当前关卡来自作品内部第 N 关，必须携带 `levelId`，避免重开误回作品第 1 关。
+4. 旧失败 run 保留为历史运行记录，不在前端继续使用。
+
+为支持第 3 点，`PuzzleRuntimeLevelSnapshot` 增加 `levelId: string | null`。
+
+## 存档投影规则
+
+复用现有 `profile_save_archive` 表，不新增拼图专属存档表。拼图存档固定规则：
+
+1. `world_key = puzzle:{entry_profile_id}`。
+2. `world_type = PUZZLE`。
+3. `profile_id = entry_profile_id`，保证同一个作品链只覆盖一条存档。
+4. `world_name` 使用当前关卡名。
+5. `subtitle` 使用 `第 N 关`。
+6. `summary_text` 使用当前状态：
+   - playing：`拼图进行中`
+   - failed：`关卡失败`
+   - cleared：`关卡已完成`
+7. `cover_image_src` 使用当前关卡正式图。
+8. `game_state_json` 保存最小拼图恢复载荷：
+   - `runtimeKind = "puzzle"`
+   - `runId`
+   - `entryProfileId`
+   - `currentProfileId`
+   - `currentLevelIndex`
+   - `currentLevelId`
+   - `status`
+
+## 写入时机
+
+SpacetimeDB 拼图运行态每次持久化 run 时同步刷新存档：
+
+1. `start_puzzle_run`：创建 run 后立即写入拼图存档。
+2. `advance_puzzle_next_level`：进入下一关后更新同一条存档。
+3. `use_puzzle_runtime_prop(extendTime)`：续时成功后更新状态。
+4. `get_puzzle_run` 导致失败态落库时，也同步更新为失败存档。
+
+排行榜提交只负责成绩与通关态，不新增存档规则；如果它把 run 状态更新为通关，也跟随 run 持久化刷新存档。
+
+## 验收
+
+1. 倒计时归零后失败弹窗有 `重新开始` 和 `继续1分钟`。
+2. 点击 `继续1分钟` 后先出现扣费确认，确认成功后失败弹窗关闭并恢复 `60` 秒倒计时。
+3. 陶泥币余额不足时确认弹窗保留，并展示错误。
+4. 点击 `重新开始` 后当前关卡重新打乱并重置倒计时。
+5. 进入拼图作品后，存档页出现 `worldType = PUZZLE` 的拼图存档。
+6. 通过一关进入下一关后，同一条存档更新到新关卡。
+7. 定向前端测试、Rust 拼图模块测试与编码检查通过。