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

doc/gameplay/运行时编译层总表.md

@@ -0,0 +1,245 @@
+# 运行时编译层总表
+
+本文档用于定义当前项目推荐的“运行时编译层”结构，也就是把系统默认值、玩法默认值、活动配置、玩家设置编译成统一运行时 profile 的中间层。
+
+目标：
+
+- 避免页面、引擎、规则层到处直接读取原始配置
+- 明确各种默认值和覆盖值的合并顺序
+- 为后续继续收口代码提供统一目标
+
+说明：
+
+- 本文档讲的是“运行时编译结构”
+- 它不替代字段字典和玩法规则文档
+- 当前已先落第一版代码骨架，后续会逐步把更多模块并到这一层
+
+---
+
+## 1. 为什么需要编译层
+
+当前系统里至少有 4 类来源：
+
+1. 系统默认值
+2. 玩法默认值
+3. 活动配置
+4. 玩家设置
+
+如果页面、引擎、规则层分别自己去判断这些来源，问题会很快出现：
+
+- 默认值散落
+- 覆盖顺序不一致
+- 同一个字段在不同页面里表现不同
+- 后续后台接入后更难维护
+
+所以推荐做法是：
+
+先编译，再运行。
+
+也就是：
+
+`默认值 / 配置 / 玩家设置 -> Runtime Profile -> MapEngine / Rule / HUD`
+
+---
+
+## 2. 当前推荐编译顺序
+
+### 2.1 规则与玩法相关
+
+推荐顺序：
+
+`系统默认值 -> 玩法默认值 -> 活动配置`
+
+适用：
+
+- 对局流程
+- 打点规则
+- 跳点规则
+- 完赛规则
+- 分值默认值
+
+### 2.2 系统设置相关
+
+推荐顺序：
+
+`系统设置默认值 -> 活动 settings 默认值 -> 玩家本地设置值`
+
+锁态单独处理：
+
+`系统默认锁态 -> 活动 settings 锁态 -> 本局锁态生命周期`
+
+说明：
+
+- 设置值可以持久化
+- 锁态不持久化
+- 锁态只在当前游戏配置运行生命周期内生效
+
+### 2.3 遥测相关
+
+推荐顺序：
+
+`系统遥测默认值 -> 活动 telemetry 默认值 -> 玩家身体数据`
+
+适用：
+
+- 年龄
+- 静息心率
+- 体重
+
+---
+
+## 3. 当前推荐 profile 结构
+
+当前建议至少编译成以下几块：
+
+### 3.1 `map`
+
+负责地图底座级运行参数：
+
+- 标题
+- 控制点绘制半径
+- 投影
+- 磁偏角
+- 初始缩放
+
+### 3.2 `game`
+
+负责玩法与规则层运行参数：
+
+- 玩法模式
+- 关门时间
+- 关门预警时间
+- 打点方式
+- 打点半径
+- 是否先选目标点
+- 是否允许跳点
+- 跳点半径
+- 跳点确认
+- 是否自动结束
+- 默认点位分值
+
+### 3.3 `settings`
+
+负责系统设置页相关运行参数：
+
+- 设置值最终结果
+- 锁态最终结果
+- 锁态生命周期是否激活
+
+### 3.4 `telemetry`
+
+负责遥测层运行参数：
+
+- 合并后的遥测配置
+- 当前玩家身体数据快照
+
+### 3.5 `presentation`
+
+负责表现层 profile：
+
+- 控制点样式
+- 轨迹样式
+- GPS 点样式
+
+### 3.6 `feedback`
+
+负责反馈层 profile：
+
+- 音效配置
+- 震动配置
+- UI 动效配置
+
+---
+
+## 4. 当前代码落点
+
+第一版运行时编译骨架已落在：
+
+- [runtimeProfileCompiler.ts](D:/dev/cmr-mini/miniprogram/game/core/runtimeProfileCompiler.ts)
+
+当前已经开始编译的内容：
+
+- `game`
+- `settings`
+- `telemetry`
+- `presentation`
+- `feedback`
+- `map`
+
+当前已接入页面 / 引擎的部分：
+
+- 设置页运行时 profile
+- 遥测层运行时 profile
+- 反馈层运行时 profile
+- 表现层 runtime profile
+- 规则层中一部分 `game profile` 字段
+
+当前接入说明：
+
+- `settings / telemetry / feedback` 已开始作为日常运行入口使用
+- 设置页大部分引擎型设置项已改成“先更新玩家设置，再统一走 `settings profile` 回灌 `MapEngine`”
+- `settings profile` 现已通过 `MapEngine.applyCompiledSettingsProfile(...)` 统一应用，不再由页面逐项调用各类 `handleSet...`
+- `presentation` 已开始通过编译层回写 `MapEngine` 表现参数
+- `game` 当前已先接入模式、关门时间、打点和跳点这组核心字段
+- `map` 已开始接入地图底座参数和配置状态文本这组基础字段
+- `MapEngine.applyRemoteMapConfig(...)` 已开始退回为原始场地与资源入口，不再继续双写已编译字段
+
+后续建议继续并入：
+
+- `MapEngine.applyRemoteMapConfig(...)` 的配置归一入口
+- `map profile`
+- 更多 `game profile` 字段
+- `courseToGameDefinition`
+
+---
+
+## 5. 当前推荐落地步骤
+
+建议按以下顺序继续收代码：
+
+1. 先让剩余设置层完全只吃 `settings profile`
+2. 再让遥测层只吃 `telemetry profile`
+3. 再让反馈层只吃 `feedback profile`
+4. 最后把玩法规则入口和表现入口都改成吃统一 profile
+
+补充：
+
+- 规则层中的目标角色也应尽量由统一运行态承载，而不是散落在 HUD 和地图展示字段里反推
+- 当前已先明确 4 类目标角色：
+  - 可打目标
+  - 引导目标
+  - HUD 目标
+  - 展示高亮目标
+
+这样风险最小，也最容易逐步验证。
+
+---
+
+## 6. 这层的边界
+
+运行时编译层应该只做两件事：
+
+1. 合并来源
+2. 产出最终运行态 profile
+
+不应该做的事：
+
+- 不直接承载页面状态
+- 不直接承载本局临时分数和目标点
+- 不直接写回配置
+- 不承担玩法执行逻辑本身
+
+也就是说：
+
+- 编译层负责“准备好”
+- 引擎和规则层负责“执行”
+
+---
+
+## 7. 当前结论
+
+后续推荐统一按这条链走：
+
+`系统默认值 -> 玩法默认值 -> 活动配置 -> 玩家设置 -> 运行时编译层 -> 引擎 / 页面 / 规则`
+
+这样配置越多，系统越不容易乱；后续后台做复杂了，也还是有一层中间结构兜住。