feat: 收敛玩法运行时配置并加入故障恢复

doc/games/顺序打点/规则说明文档.md

@@ -0,0 +1,302 @@
+# 顺序打点规则说明文档
+
+本文档用于定义 `classic-sequential` 在**最小模板**下的系统默认规则，作为后续实现、联调和配置扩展的共同基线。
+
+目标：
+
+- 明确顺序打点在“不额外写规则字段”时应该怎么跑
+- 把开局、打点、跳点、答题、结束和结算流程写清楚
+- 为后续配置化拆分提供规则依据
+
+如果后续要继续扩写更多正式玩法文档，建议统一使用：
+
+- [玩法设计文档模板](D:/dev/cmr-mini/doc/gameplay/玩法设计文档模板.md)
+
+---
+
+## 1. 适用范围
+
+本文默认规则适用于：
+
+- `game.mode = "classic-sequential"`
+- 使用最小顺序赛模板启动
+- 未显式覆盖开局流程、跳点、答题、结算和默认表现规则
+
+本文定义的是**系统默认行为**，不是所有字段都必须先配置出来。
+
+---
+
+## 2. 一句话规则
+
+玩家进入游戏后先看到起点，完成起点打卡后才正式开赛；中间控制点允许跳点；每个成功打到的普通控制点默认先完成基础得分结算；如某点显式配置了答题 CTA，则该点打卡后再进入答题流程；完成终点打卡后结束比赛并进入结算页。
+
+---
+
+## 3. 默认流程总览
+
+### 3.1 进入游戏
+
+- 系统进入“待起跑”状态
+- 地图默认只显示：
+  - 起点
+  - 玩家当前位置
+  - 基础 HUD
+- 普通控制点、终点、路线和腿线默认不显示
+- 页面提示玩家：需要先打开始点，比赛才会正式开始并开始计时
+- 最小模板下，点击检查点默认不弹详情卡
+
+### 3.2 打开始点
+
+- 玩家首次成功打开始点后，比赛正式开始
+- 系统立即初始化本局数据
+- 系统开始计时
+- 系统显示全部普通控制点、终点和路线腿线
+- 默认只给出“比赛开始”短反馈，并同步更新引导提示和 HUD
+- 最小模板下，开始点完成后默认不弹白色内容卡
+- 默认关门时间为开赛后 `2` 小时
+- 当距离关门时间小于等于 `10` 分钟时，HUD 时间区默认切换为倒计时强调样式
+
+### 3.3 中间控制点推进
+
+- 玩家按顺序推进普通控制点
+- 默认允许跳点
+- 底部 HUD 信息面板默认同步显示当前目标摘要与目标距离
+- 成功打到普通控制点后：
+  - 该点记为成功
+  - 获得该点基础分
+  - 最小模板下默认不弹答题卡
+  - 如显式配置答题 CTA，则在该点完成后进入答题
+
+### 3.4 打结束点
+
+- 当所有中间控制点都已经被标记为“成功”或“跳过”后，终点才可生效
+- 成功打结束点后：
+  - 系统停止计时
+  - 先给出完成短反馈
+  - 直接进入默认成绩结算页
+  - 默认不再额外叠加终点白色内容卡
+- 如果超过关门时间仍未完赛，系统按“超时结束”处理
+- “超时结束”需与正常完赛、主动退出明确区分
+
+---
+
+## 4. 局状态与数据初始化
+
+### 4.1 默认局状态
+
+顺序打点默认包含以下状态：
+
+1. `ready`
+2. `running`
+3. `finished`
+4. `settled`
+
+### 4.2 起点打卡后的初始化数据
+
+首次成功打开始点时，系统至少初始化以下运行时数据：
+
+- `startTime`
+- `elapsedTime`
+- `currentTargetIndex`
+- `completedControls`
+- `skippedControls`
+- `visitedControls`
+- `score`
+- `baseScore`
+- `quizBonusScore`
+- `quizCorrectCount`
+- `quizWrongCount`
+- `quizTimeoutCount`
+- `finishTime`
+
+---
+
+## 5. 打点规则
+
+### 5.1 开始点
+
+- 开始点必须打卡
+- 开始点不弹答题卡
+- 开始点默认只给短反馈和引导更新
+- 开始点默认不弹白色内容卡
+- 未打开始点前进入其他控制点范围，不触发正式打点逻辑
+
+### 5.2 普通控制点
+
+- 默认按顺序推进
+- 当前目标点进入打点半径后可成功打点
+- 同一点成功后不得重复得分，不得重复出题
+- 同一点再次进入范围时，只保留已完成状态展示，不重复触发结算
+
+### 5.3 结束点
+
+- 结束点必须打卡
+- 结束点不弹答题卡
+- 结束点默认只给完成短反馈并直接进入结果页
+- 结束点默认不弹白色内容卡
+- 结束点不可被跳过
+
+---
+
+## 6. 跳点规则
+
+### 6.1 默认是否允许跳点
+
+- 默认允许跳点
+
+### 6.2 默认跳点半径
+
+- 默认跳点半径 = 打点半径的 `2` 倍
+- 例如打点半径为 `5m` 时，默认跳点半径为 `10m`
+- 默认点击跳点按钮后先弹出确认框
+
+### 6.3 默认跳点判定
+
+- 当玩家尚未完成当前目标点，但进入后续普通控制点的跳点半径时：
+  - 当前目标点标记为“跳过”
+  - 当前进入的后续点允许按“成功到达”处理
+- 跳点后流程继续向后推进
+
+### 6.4 跳点结算
+
+- 被跳过的点不得基础分
+- 被跳过的点不弹答题卡
+- 被跳过的点不计入成功打点数
+
+### 6.5 不可跳点对象
+
+- 开始点不可跳
+- 结束点不可跳
+
+---
+
+## 7. 计分与答题规则
+
+### 7.1 普通控制点默认分值
+
+每个普通控制点默认基础分为 `1` 分。
+
+### 7.2 基础分结算
+
+- 普通控制点成功打点后，立即获得 `1` 分基础分
+- 跳过点不得基础分
+
+### 7.3 默认答题规则
+
+- 最小模板下默认不启用答题
+- 如需答题，需显式为对应点位配置 `quiz` CTA
+- 显式启用后，答题时比赛继续计时，不暂停比赛时间
+
+### 7.4 答题结算
+
+- 最小模板下默认不存在答题奖励分
+- 如显式启用答题，则按该点题卡配置进行奖励结算
+
+### 7.5 不弹题对象
+
+- 开始点不弹题
+- 结束点不弹题
+- 跳过点不弹题
+
+---
+
+## 8. 地图与表现默认规则
+
+### 8.1 起跑前显示
+
+- 起跑前仅显示开始点
+- 其他普通控制点、终点和腿线隐藏
+
+### 8.2 起跑后显示
+
+- 打完开始点后显示全部普通控制点、终点和路线腿线
+- 当前目标点需要有明确强调态
+- 底部 HUD 信息面板默认显示当前目标点摘要，并随推进自动更新
+
+### 8.3 点位默认表现
+
+- 默认路线和控制点主色参考传统定向运动紫红色系
+- 开始点、结束点、当前目标点都应带动效
+- 已成功点默认变灰
+- 已跳过点使用另一套默认颜色，建议为偏橙色系，避免与已完成点混淆
+
+### 8.4 腿线默认表现
+
+- 默认显示腿线
+- 腿线带电流动效
+- 重点强调当前目标腿线
+- 已完成腿线弱化显示
+
+---
+
+## 9. 反馈与结算页默认规则
+
+### 9.1 开始反馈
+
+- 开始点成功后默认给出“比赛开始”类短反馈
+- 同时更新黑色引导提示条和 HUD 当前目标摘要
+- 最小模板下默认不弹开始白卡
+- 如需开始点完成后展示白色内容卡，需显式开启对应点位的 `autoPopup = true`
+
+### 9.2 结束反馈
+
+- 结束点成功后默认先给短反馈
+- 随后直接进入默认成绩结算页
+- 默认不再额外弹出终点白色内容卡
+- 如需再次查看终点说明，需显式配置点击内容能力
+
+### 9.3 默认成绩结算页
+
+默认结算页至少显示：
+
+- 总用时
+- 总分
+- 基础分
+- 答题奖励分
+- 成功打点数
+- 跳过点数
+- 答题正确数
+- 答题错误数
+- 答题超时数
+- 是否完赛
+
+---
+
+## 10. 边界与容错默认规则
+
+### 10.1 GPS 防重复触发
+
+- 同一点成功结算后，系统应有短暂防抖或冷却，避免 GPS 抖动导致重复触发
+
+### 10.2 重复进入已完成点
+
+- 已完成点再次进入范围时不重复得分、不重复答题、不重复弹完成提示
+
+### 10.3 重复进入已跳过点
+
+- 已跳过点再次进入范围时保持“跳过”状态，不回补得分或答题
+
+### 10.4 页面中断恢复
+
+- 小程序切后台或页面重进后，默认应恢复当前比赛状态
+- 已开始的比赛默认不应自动重开
+
+---
+
+## 11. 与最小模板的关系
+
+顺序赛最小模板只需要保证以下骨架存在：
+
+- `playfield.kind = "course"`
+- `game.mode = "classic-sequential"`
+- `game.punch.policy`
+- `game.punch.radiusMeters`
+
+其余流程默认按本文档执行。
+
+也就是说，本文档定义的是：
+
+- 最小模板下的系统默认局流程
+- 后续配置化扩展前的默认产品行为
+- 顺序赛样例配置和实现验收时的基准口径
+