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,58 +0,0 @@
|
||||
# 拼图运行态低延迟交互前端化修正 2026-05-02
|
||||
|
||||
## 背景
|
||||
|
||||
本次检查发现正式平台入口的拼图运行态存在后端裁决回流：
|
||||
|
||||
1. 作品详情、公开作品卡和结果页试玩会启动后端 run。
|
||||
2. `PuzzleRuntimeShell` 的交换和拖动回调在非本地 run 时会调用 `swapPuzzlePieces`、`dragPuzzlePieceOrGroup`。
|
||||
3. 服务端 run snapshot 如果直接覆盖前端当前棋盘，会让移动、交换、合并和通关反馈出现延迟或回退。
|
||||
|
||||
这与 PRD 中“前端以本地计算得到的 `allTilesResolved = true` 或 `status = cleared` 作为本关通关真相；后端不再参与拼块布局裁决”的规则冲突。
|
||||
|
||||
## 修正口径
|
||||
|
||||
正式平台入口采用混合运行态：
|
||||
|
||||
1. 正式平台开局仍调用后端 `startPuzzleRun`，保留真实 `runId`、游玩记录、排行榜和下一关存储锚点。
|
||||
2. 点击交换只调用 `swapLocalPuzzlePieces`。
|
||||
3. 拖动单块或合并块只调用 `dragLocalPuzzlePiece`。
|
||||
4. 自动合并、拆分、合并块整体平移、被覆盖块交换和通关判定都以前端当前 `PuzzleRunSnapshot` 为准。
|
||||
5. 通关后调用后端 `submitPuzzleLeaderboard` 持久化成绩并读取真实排行榜；前端只合并排行榜与下一关 handoff，不用后端棋盘覆盖当前棋盘。
|
||||
6. 点击同作品下一关调用后端 `advancePuzzleNextLevel`，由 SpacetimeDB 返回新的运行态快照。
|
||||
7. 当前作品没有下一关时，通关弹窗展示后端 handoff 返回的相似作品；用户点击具体候选作品时直接 `startPuzzleRun(profileId, null)`，从目标作品第 `1` 关重新开始。
|
||||
8. 失败状态点击“重新开始”时，正式 run 使用当前关 `levelId` 重新 `startPuzzleRun`，草稿/本地 run 使用本地重建，二者都保留当前失败关卡。
|
||||
9. 结果页草稿试玩没有正式后端 run 时，继续使用本地 run、local leaderboard 和本地下一关兜底。
|
||||
10. 运行态输入采用全项目通用的 `src/services/input-devices/` 抽象层承接，指针、触控、mocap 等设备都先归一为 `press / move / release / tap / drop` 拖拽语义，再由拼图运行态解析具体拼块和落点。
|
||||
11. mocap `grab` 不是点击选中语义，而是持续拖拽语义；松手时按当前棋盘归一坐标提交 drop。合并大块只需要提交其中任一成员拼块 `pieceId`，本地拼图运行时会按 `mergedGroupId` 解析整组平移。
|
||||
12. 拼图作品详情或开局遇到后端 `404 / NOT_FOUND / 资源不存在` 时，平台入口不再停留在空详情或运行态错误页，而是清理当前拼图详情/run 状态并返回首页。
|
||||
|
||||
## 工程落点
|
||||
|
||||
1. `src/services/puzzle-runtime/puzzleLocalRuntime.ts`
|
||||
- `startLocalPuzzleRun` 支持按 `levelId` 启动。
|
||||
- `advanceLocalPuzzleLevel` 仅作为草稿试玩和无后端 run 的兜底。
|
||||
- 正式平台的移动、交换、合并、拆分和通关裁决仍复用本地函数，避免交互延迟。
|
||||
2. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
- 平台拼图开局、恢复存档、排行榜、下一关接回后端。
|
||||
- 正式平台入口不再调用 `/api/runtime/puzzle/runs/{runId}/swap`、`/drag`。
|
||||
- 后端排行榜返回的 run 只合并排行榜和 `nextLevelMode / nextLevelProfileId / nextLevelId / recommendedNextWorks`，不覆盖当前棋盘。
|
||||
- 相似作品候选卡点击启动目标作品新 run；失败重开按当前关 `levelId` 启动新 run。
|
||||
3. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`
|
||||
- 公开拼图玩法交互测试断言前端本地交换函数被调用。
|
||||
- 同时断言后端 `swap / drag` 不参与棋盘交互，后端 `leaderboard / next-level` 继续参与非即时链路。
|
||||
4. `src/services/input-devices/`
|
||||
- `runtimeDragInputController` 提供设备无关的拖拽会话状态机。
|
||||
- `runtimeInputGeometry` 提供屏幕坐标、归一坐标和网格命中的通用转换能力。
|
||||
- 玩法组件只传入“这个点对应哪个目标”和“drop 到哪个目标”的玩法解释，不在输入层写拼图专用规则。
|
||||
5. `src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`
|
||||
- 鼠标/触控与 mocap 共用同一个 runtime drag controller。
|
||||
- 合并块成员不再被 mocap 路径过滤；mocap 可从合并块任一占用格抓取，并复用本地运行时的大块拖拽规则。
|
||||
6. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
|
||||
- `openPuzzleDetail`、`openPuzzlePublicWorkDetail`、`startPuzzleRunFromProfile` 对拼图作品缺失统一回首页。
|
||||
|
||||
## 边界
|
||||
|
||||
本次只收回拼图玩法内的移动、交换、合并、拆分和通关裁决。创作 Agent、作品保存、发布、公开广场读取、作品详情读取、作品改造、排行榜、同作品下一关、相似候选生成、失败重开和游玩记录仍走现有后端链路。
|
||||
|
||||
旧 `SERVER_RS_DDD_WP_PZ_RUNTIME_BACKEND_TRUTH_CLOSURE_2026-05-01.md` 作为历史收尾记录保留；若与本文冲突，以本文的“低延迟棋盘前端裁决，非即时链路后端持久化”口径为准。
|
||||
Reference in New Issue
Block a user