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

doc/config/配置选项字典.md

@@ -23,8 +23,9 @@
 ```json
 {
   "schemaVersion": "1",
-  "version": "2026.03.27",
+  "version": "2026.03.31",
   "app": {},
+  "settings": {},
   "map": {},
   "playfield": {},
   "game": {},
@@ -54,6 +55,12 @@
 - 类型：`object`
 - 说明：活动级基础信息
 
+### `settings`
+
+- 类型：`object`
+- 说明：系统设置页默认值与锁态配置
+- 备注：只控制设置页公共项，不属于具体玩法规则本体
+
 ### `map`
 
 - 类型：`object`
@@ -81,6 +88,40 @@
 
 ---
 
+## `settings` 字段补充
+
+推荐结构：
+
+```json
+{
+  "settings": {
+    "autoRotateEnabled": {
+      "value": true,
+      "isLocked": false
+    },
+    "trackDisplayMode": {
+      "value": "tail",
+      "isLocked": true
+    },
+    "gpsMarkerStyle": {
+      "value": "beacon",
+      "isLocked": false
+    }
+  }
+}
+```
+
+规则：
+
+- `value` 表示该设置项的活动默认值
+- `isLocked` 表示该设置项是否允许玩家修改
+- `value` 会和玩家本地持久化值一起参与解析
+- `isLocked` 不持久化，只受系统默认值和活动配置控制
+- 玩家不能在页面里修改锁态
+- `isLocked` 只在当前游戏配置运行生命周期内生效；本局结束或主动退出后失效
+
+---
+
 ## 3. `app` 字段
 
 ### `app.id`
@@ -172,23 +213,63 @@
 
 ---
 
-## 6. `playfield.controlOverrides`
+## 6. `playfield.controlDefaults` / `playfield.controlOverrides`
 
-`playfield.controlOverrides` 用于对起点、检查点、终点做内容或分值覆盖。
+推荐优先使用：
 
-### 6.1 key 命名规则
+- `playfield.controlDefaults`：活动级默认
+- `playfield.controlOverrides`：单点重载
+
+默认覆盖顺序：
+
+`系统默认值 -> 玩法默认值 -> playfield.controlDefaults -> playfield.controlOverrides`
+
+### 6.1 `playfield.controlDefaults`
+
+- 类型：`object`
+- 说明：普通检查点的活动级默认配置
+- 适用：普通检查点，不直接作用于起点和终点
+
+当前支持字段：
+
+- `score`
+- `template`
+- `title`
+- `body`
+- `clickTitle`
+- `clickBody`
+- `autoPopup`
+- `once`
+- `priority`
+- `ctas`
+- `contentExperience`
+- `clickExperience`
+- `pointStyle`
+- `pointColorHex`
+- `pointSizeScale`
+- `pointAccentRingScale`
+- `pointGlowStrength`
+- `pointLabelScale`
+- `pointLabelColorHex`
+
+### 6.2 `playfield.controlOverrides`
+
+`playfield.controlOverrides` 用于对起点、检查点、终点做单点覆盖。
+
+### 6.3 key 命名规则
 
 - 起点：`start-1`
 - 普通检查点：`control-1`、`control-2`、`control-3`
 - 终点：`finish-1`
 
-### 6.2 当前支持字段
+### 6.4 当前支持字段
 
 #### `score`
 
 - 类型：`number`
 - 说明：积分赛控制点分值
 - 适用：积分赛
+- 备注：如果同时配置了 `playfield.controlDefaults.score`，则当前点以单点值为准
 
 #### `title`
 
@@ -216,20 +297,22 @@
 
 - 类型：`string`
 - 说明：点击控制点时弹出的标题
-- 默认逻辑：未配置时回退到 `title`
+- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
 
 #### `clickBody`
 
 - 类型：`string`
 - 说明：点击控制点时弹出的正文
-- 默认逻辑：未配置时回退到 `body`
+- 默认逻辑：最小模板下默认不启用；仅在显式配置点击内容能力时生效
 
 #### `autoPopup`
 
 - 类型：`boolean`
-- 说明：完成该点后是否自动弹出内容
-- 建议默认值：`true`
+- 说明：完成该点后是否自动弹出内容卡
+- 建议默认值：最小模板下 `false`
 - 特殊逻辑：如果当前玩法是自动打点，即 `game.punch.policy = "enter"`，则无论这里如何配置，**都不自动弹出**
+- 补充说明：该字段只控制内容卡弹出
+- 补充说明：系统默认白卡已改为“显式配置启用”，未开启 `autoPopup` 时，起点和普通点完成后不弹白卡
 
 #### `once`
 
@@ -415,7 +498,7 @@
     "template": "focus",
     "title": "比赛结束",
     "body": "恭喜完成本次路线。",
-    "autoPopup": true,
+    "autoPopup": false,
     "once": true,
     "priority": 2,
     "clickTitle": "终点说明",
@@ -450,7 +533,11 @@
 
 - 类型：`boolean`
 - 说明：是否需要手动点击开始
-- 建议默认值：`true`
+- 建议默认值：
+  - 顺序赛：`false`
+  - 积分赛：`false`
+- 备注：
+  - 进入页面后先进入待起跑态，通过开始点打卡正式开赛
 
 ### `game.session.requiresStartPunch`
 
@@ -474,6 +561,14 @@
 - 说明：是否打完最后控制点自动结束
 - 建议默认值：`false`
 
+### `game.session.minCompletedControlsBeforeFinish`
+
+- 类型：`number`
+- 说明：终点生效前至少需要完成的普通检查点数量
+- 建议默认值：
+  - 顺序赛：`0`
+  - 积分赛：`1`
+
 ### `game.session.maxDurationSec`
 
 - 类型：`number`
@@ -517,19 +612,22 @@
 
 - 类型：`boolean`
 - 说明：是否允许跳点
-- 建议默认值：`false`
+- 建议默认值：
+  - 顺序赛：`true`
+  - 积分赛：`false`
 
 ### `game.sequence.skip.radiusMeters`
 
 - 类型：`number`
 - 说明：跳点半径
-- 建议默认值：`30`
+- 建议默认值：
+  - 顺序赛：`game.punch.radiusMeters * 2`
 
 ### `game.sequence.skip.requiresConfirm`
 
 - 类型：`boolean`
 - 说明：跳点是否需要确认
-- 建议默认值：`true`
+- 建议默认值：`false`
 
 ---
 
@@ -544,8 +642,11 @@
 ### `game.scoring.defaultControlScore`
 
 - 类型：`number`
-- 说明：积分赛默认控制点分值
-- 建议默认值：`10`
+- 说明：普通控制点未单独配置时的默认基础分
+- 建议默认值：
+  - 顺序赛：`1`
+  - 积分赛：`10`
+- 适用：顺序赛、积分赛
 
 ---
 
@@ -596,6 +697,9 @@
 - 建议默认值：
   - 顺序赛：`false`
   - 积分赛：`true`
+- 备注：
+  - 顺序赛默认要求所有中间点都已被标记为“成功”或“跳过”后，终点才可生效
+  - 积分赛默认开赛后终点始终可结束，不需要先设为目标点
 
 ---
 
@@ -641,6 +745,50 @@
 - 说明：UI 动效 profile
 - 建议默认值：`default`
 
+### `game.audio.distantDistanceMeters`
+
+- 类型：`number`
+- 说明：远距离提示音的最大生效距离，超出该距离默认静默
+- 建议默认值：`80`
+
+### `game.audio.approachDistanceMeters`
+
+- 类型：`number`
+- 说明：接近提示音的最大生效距离
+- 建议默认值：`20`
+
+### `game.audio.readyDistanceMeters`
+
+- 类型：`number`
+- 说明：可打点提示音的最大生效距离
+- 建议默认值：`5`
+- 备注：
+  - 运行时不会小于 `game.punch.radiusMeters`
+
+### `game.audio.cues["guidance:distant"].loopGapMs`
+
+- 类型：`number`
+- 说明：远距离提示音循环间隔，单位毫秒
+- 建议默认值：`4800`
+
+### `game.audio.cues["guidance:approaching"].loopGapMs`
+
+- 类型：`number`
+- 说明：接近提示音循环间隔，单位毫秒
+- 建议默认值：`950`
+
+### `game.audio.cues["guidance:ready"].loopGapMs`
+
+- 类型：`number`
+- 说明：可打点提示音循环间隔，单位毫秒
+- 建议默认值：`650`
+
+### `game.audio.cues["guidance:distant" | "guidance:approaching" | "guidance:ready"].volume`
+
+- 类型：`number`
+- 说明：三档距离提示音各自音量
+- 建议范围：`0 ~ 1`
+
 ---
 
 ## 17. `resources`
@@ -710,6 +858,8 @@
 
 - 类型：`object`
 - 说明：顺序赛已跳过点样式
+- 备注：
+  - 默认建议使用偏橙色系，与已完成灰色态区分
 
 ### `game.presentation.sequential.controls.start`
 
@@ -730,6 +880,9 @@
   - `colorHex`：十六进制颜色
   - `widthScale`：路线腿宽度倍率
   - `glowStrength`：路线腿光晕强度
+- 备注：
+  - 默认建议使用传统定向运动紫红色系
+  - 默认配合电流动效使用
 
 ### `game.presentation.sequential.legs.completed`
 
@@ -740,6 +893,17 @@
 
 - 类型：`object`
 - 说明：对指定路线腿做局部样式覆盖
+- 建议：优先使用 `playfield.legDefaults` 写整场腿线默认，再用 `legOverrides` 写单腿例外
+
+### `playfield.legDefaults`
+
+- 类型：`object`
+- 说明：腿线的活动级默认样式
+- 当前支持字段：
+  - `style`
+  - `colorHex`
+  - `widthScale`
+  - `glowStrength`
 - 键名建议：
   - `leg-1`
   - `leg-2`
@@ -766,6 +930,7 @@
 
 - 类型：`object`
 - 说明：积分赛默认点位样式
+- 当前默认建议使用传统圆圈样式，编号绘制在圆圈内
 
 ### `game.presentation.scoreO.controls.focused`
 
@@ -810,8 +975,8 @@
     "controls": {
       "scoreBands": [
         { "min": 0, "max": 19, "style": "classic-ring", "colorHex": "#56ccf2" },
-        { "min": 20, "max": 49, "style": "double-ring", "colorHex": "#f2c94c" },
-        { "min": 50, "max": 999999, "style": "badge", "colorHex": "#eb5757" }
+        { "min": 20, "max": 49, "style": "classic-ring", "colorHex": "#f2c94c" },
+        { "min": 50, "max": 999999, "style": "double-ring", "colorHex": "#eb5757" }
       ]
     }
   }
@@ -1049,7 +1214,7 @@
 
 - 能有默认值的尽量给默认值
 - 控制点内容类字段缺失时走默认文案
-- `clickTitle/clickBody` 缺失时回退到 `title/body`
+- `clickTitle/clickBody` 在最小模板下默认关闭，不再回退到 `title/body`
 - 自动打点模式下不自动弹内容
 - 内容优先级未配置时使用普通点 `1`、终点 `2`
 
@@ -1057,6 +1222,56 @@
 
 **大部分配置项都不是强制必填，先保证主骨架完整即可。**
 
+### 22.1 顺序赛最小模板默认流程
+
+如果只提供顺序赛最小模板，系统默认按以下流程处理：
+
+- 进入游戏后只显示开始点，提示玩家先打开始点
+- 成功打开始点后，显示全部普通控制点、终点和腿线，并正式开始计时
+- 开始点和结束点默认不弹题，只弹提示信息
+- 普通控制点默认允许跳点
+- 默认跳点半径为打点半径的 `2` 倍
+- 普通控制点成功打点后立即获得 `1` 分基础分
+- 最小模板下默认不弹题
+- 如需答题，需显式为对应点位配置 `quiz` CTA
+- 跳过点不弹题、不得分
+- 成功打结束点后停止计时，弹出结束提示，随后进入默认结算页
+
+### 22.2 顺序赛最小模板默认表现
+
+- 起跑前只显示开始点
+- 打完开始点后显示完整路线
+- 默认路线主色参考传统定向运动紫红色
+- 默认腿线带电流动效
+- 开始点、结束点、当前目标点都应有动效强调
+- 已完成点默认变灰
+- 已跳过点默认使用另一套区分色
+
+### 22.3 积分赛最小模板默认流程
+
+如果只提供积分赛最小模板，系统默认按以下流程处理：
+
+- 进入游戏后只显示开始点，提示玩家先打开始点
+- 成功打开始点后，显示全部积分点和结束点，并正式开始计时
+- 开始点和结束点默认不弹题，只弹提示信息
+- 玩家默认不需要先点击积分点
+- 底部 HUD 信息面板默认显示当前目标摘要、目标距离和总分 / 收集进度摘要
+- 任意未收集积分点进入范围时都可生效
+- 成功打点后默认立即获得该点基础分
+- 最小模板下默认不弹题
+- 如需答题，需显式为对应点位配置 `quiz` CTA
+- 默认至少完成 `1` 个普通积分点后，结束点才解锁，且不需要先设为目标点
+- 成功打结束点后停止计时，弹出结束提示，随后进入默认结算页
+
+### 22.4 积分赛最小模板默认表现
+
+- 起跑前只显示开始点
+- 打完开始点后显示全部积分点和结束点
+- 当前目标点默认要有更强高亮和动效
+- 默认所有积分点显示分值标签
+- 已收集点默认变灰
+- 默认不显示腿线
+
 ---
 
 ## 23. 维护约定
@@ -1072,4 +1287,3 @@
 - 服务端可对照
 - 后台可录入
 - 客户端联调时有统一参考
-