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,127 +0,0 @@
|
||||
# 拼图运行时限时与道具系统设计 2026-04-29
|
||||
|
||||
## 背景
|
||||
|
||||
拼图运行时从纯粹的无压解谜升级为限时关卡，需要同时补齐三类体验：
|
||||
|
||||
1. 不同难度有明确倒计时，超时即失败。
|
||||
2. 底部固定 3 个轻量道具：提示、查看原图、冻结时间。
|
||||
3. 道具使用必须经过确认弹窗并消耗 `1` 泥点，确认弹窗期间暂停关卡计时。
|
||||
|
||||
本设计只处理拼图运行时，不改拼图创作链、发布链和广场推荐链。
|
||||
|
||||
## 运行态字段
|
||||
|
||||
`PuzzleRuntimeLevelSnapshot` 增加以下字段：
|
||||
|
||||
1. `timeLimitMs`：当前关卡限时。
|
||||
2. `remainingMs`：后端或本地运行态计算出的剩余时间。
|
||||
3. `pausedAccumulatedMs`：已累计暂停时长。
|
||||
4. `pauseStartedAtMs`：当前是否处于暂停中；有值表示暂停开始时间。
|
||||
5. `freezeUntilMs`：冻结时间道具生效截止时间；冻结期间倒计时不减少。
|
||||
|
||||
`status` 增加 `failed`。当 `remainingMs <= 0` 且关卡尚未通关时，状态进入 `failed`，后续交换、拖动、排行榜提交都拒绝。
|
||||
|
||||
## 难度限时
|
||||
|
||||
拼图关卡切割规格和倒计时由统一关卡配置函数解析，不再按网格规模单独推导时间：
|
||||
|
||||
| 关卡 | 切割规格 | 限时 |
|
||||
| -------- | -------- | ---------- |
|
||||
| 第 1 关 | `3x3` | `300000ms` |
|
||||
| 第 2 关 | `4x4` | `300000ms` |
|
||||
| 第 3 关 | `5x5` | `300000ms` |
|
||||
| 第 4 关 | `5x5` | `210000ms` |
|
||||
| 第 5 关 | `5x5` | `210000ms` |
|
||||
| 第 6 关 | `6x6` | `240000ms` |
|
||||
| 第 7 关 | `5x5` | `210000ms` |
|
||||
| 第 8 关 | `7x7` | `270000ms` |
|
||||
| 第 9 关 | `5x5` | `240000ms` |
|
||||
| 第 10 关 | `7x7` | `270000ms` |
|
||||
|
||||
第 11 关开始，每 6 关循环复用第 5 关到第 10 关的配置，即 `5x5/210000ms`、`6x6/240000ms`、`5x5/210000ms`、`7x7/270000ms`、`5x5/240000ms`、`7x7/270000ms`。
|
||||
|
||||
同作品下一关必须使用同一个运行时关卡序号继续推进。跨作品相似推荐只切换到候选作品的第一张图，运行时关卡序号、切割规格和倒计时继续按当前 run 累进，不重置难度循环。
|
||||
|
||||
失败状态点击“重新开始”时，不进入作品第 `1` 关，而是重开当前失败关卡：前端需要传当前关 `levelId`，服务端按该 `levelId` 在作品内的位置恢复 `currentLevelIndex`、切割规格和倒计时。
|
||||
|
||||
后续若扩展更多难度，只能通过同一个关卡配置解析函数扩展，不允许在 UI 里写死另一套时间。
|
||||
|
||||
## 计时规则
|
||||
|
||||
有效消耗时间计算：
|
||||
|
||||
```text
|
||||
effectiveElapsedMs = nowMs - startedAtMs - pausedAccumulatedMs - activeFreezeElapsedMs
|
||||
remainingMs = max(0, timeLimitMs - effectiveElapsedMs)
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
1. 弹窗打开、设置面板打开、查看原图覆盖打开时，运行态需要暂停。
|
||||
2. 冻结时间生效时，画面播放冻结特效，并展示冻结剩余时长。
|
||||
3. 通关时 `elapsedMs` 使用有效消耗时间，不把确认弹窗、查看原图和冻结时间计入成绩。
|
||||
4. 失败后保留棋盘，不弹通关结算。
|
||||
5. 正式后端 run 的前端倒计时归零时，需要主动刷新一次 `getPuzzleRun`，让 SpacetimeDB 侧把 `failed` 状态写回快照，避免只停留在本地视觉失败。
|
||||
|
||||
## 道具规则
|
||||
|
||||
### 提示
|
||||
|
||||
提示道具只演示，不替玩家移动。
|
||||
|
||||
演示对象选择：
|
||||
|
||||
1. 优先选当前棋盘中拼块数量最多、且尚未完全处于正确位置的合并块。
|
||||
2. 若没有合并块，选择一个不在正确格子的单块。
|
||||
3. 演示从当前所在格移动到该块锚点的正确格，结束后回到原位。
|
||||
|
||||
### 查看原图
|
||||
|
||||
查看原图是开关按钮：
|
||||
|
||||
1. 打开后把原图以半透明方式覆盖在拼图棋盘上。
|
||||
2. 覆盖期间暂停倒计时；确认弹窗关闭到覆盖层显示之间不得恢复计时，正式后端 run 也需要保持 `pauseStartedAtMs`。
|
||||
3. 再次点击关闭覆盖并恢复计时。
|
||||
|
||||
### 冻结时间
|
||||
|
||||
冻结时间确认后：
|
||||
|
||||
1. 播放冻结视觉特效。
|
||||
2. 显示冻结剩余时长。
|
||||
3. 第一版冻结 `10000ms`。
|
||||
4. 若玩家打开冻结确认弹窗前视觉上仍是 `playing`，但确认扣费期间正式 run 已被服务端计时结算为 `failed`，服务端不得返回“操作不合法”。本次调用视为一次边界同步，已预扣费用必须退款，只返回失败态快照并刷新存档；前端关闭道具确认窗，展示失败面板，不播放冻结特效。
|
||||
|
||||
## 计费规则
|
||||
|
||||
每次确认使用道具消耗 `1` 泥点。
|
||||
|
||||
正式后端运行态复用现有资产操作钱包预扣链路，新增道具 `asset_kind`：
|
||||
|
||||
1. `puzzle_prop_hint`
|
||||
2. `puzzle_prop_preview`
|
||||
3. `puzzle_prop_freeze_time`
|
||||
|
||||
本地调试 run 没有真实用户钱包，不伪造扣费，只保留同样的确认交互与运行态效果。
|
||||
|
||||
若扣费或道具过程失败，确认弹窗保持打开并继续暂停倒计时，在弹窗内展示失败原因；只有成功确认后才关闭弹窗并播放对应反馈。
|
||||
|
||||
补充规则：冻结时间的边界同步不属于道具使用成功。服务端若发现 run 已超时失败，应退回本次预扣、把失败态落库并返回最新快照，避免玩家在确认窗内看到“操作不合法”。
|
||||
|
||||
## UI 规则
|
||||
|
||||
1. 底部只放 3 个道具按钮，不写规则说明文案。
|
||||
2. 点击道具弹出独立确认窗口，不在底栏下方展开。
|
||||
3. 确认窗口打开期间暂停计时。
|
||||
4. 按钮使用图标和短标签；不可用时降低透明度。
|
||||
5. 失败状态使用简洁弹窗展示，可返回或重新开始，不与通关结算混用。
|
||||
|
||||
## 画布表现修正
|
||||
|
||||
本轮同步修正合并块视觉：
|
||||
|
||||
1. 合并块之间不再使用额外 `p-1` 缝隙，拼图块需要贴合。
|
||||
2. 单块和大块使用同一套边界描边宽度与颜色。
|
||||
3. 外轮廓和凹入转角都需要圆角化。
|
||||
4. 新合并产生时，在新大块中心播放一次简洁闪光，不显示文字提示。
|
||||
Reference in New Issue
Block a user