Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,98 +0,0 @@
|
||||
# 拼图失败续时与存档投影设计 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 拼图模块测试与编码检查通过。
|
||||
Reference in New Issue
Block a user