# 拼图失败续时与存档投影设计 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`

通关存档投影有一个额外规则：如果当前关卡已通关，并且 `refresh_next_level_handoff` 已经确认同作品存在下一关，则存档立即投影到同作品下一关入口，`status` 写为 `playing`，`subtitle / world_name / cover_image_src / currentLevelId` 都使用下一关。若当前作品没有下一关、只存在相似作品候选，存档保持当前已通关关卡，等待玩家在结算弹窗里选择相似作品，不能提前替玩家切换到某个候选作品。

## 写入时机

SpacetimeDB 拼图运行态每次持久化 run 时同步刷新存档：

1. `start_puzzle_run`：创建 run 后立即写入拼图存档。
2. `advance_puzzle_next_level`：进入下一关后更新同一条存档。
3. `use_puzzle_runtime_prop(extendTime)`：续时成功后更新状态。
4. `get_puzzle_run` 导致失败态落库时，也同步更新为失败存档。
5. `submit_puzzle_leaderboard_entry`：正式 run 提交成绩并把当前关标记为已通关时，先刷新下一关 handoff，再按上面的通关投影规则同步存档。

前端在 `startPuzzleRun / usePuzzleProp / submitPuzzleLeaderboard / advancePuzzleLevel / getPuzzleRun` 成功后主动刷新存档列表，避免存档页停留在进入作品前或上一关的旧投影。

## 验收

1. 倒计时归零后失败弹窗有 `重新开始` 和 `继续1分钟`。
2. 点击 `继续1分钟` 后先出现扣费确认，确认成功后失败弹窗关闭并恢复 `60` 秒倒计时。
3. 光点余额不足时确认弹窗保留，并展示错误。
4. 点击 `重新开始` 后当前关卡重新打乱并重置倒计时。
5. 进入拼图作品后，存档页出现 `worldType = PUZZLE` 的拼图存档。
6. 通过一关后，只要后端确认同作品下一关存在，同一条存档立即更新到新关卡；没有同作品下一关时保留已完成关卡，等待玩家选择相似作品。
7. 定向前端测试、Rust 拼图模块测试与编码检查通过。