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

doc/gameplay/游戏规则架构.md

@@ -0,0 +1,380 @@
+# 游戏规则架构
+
+本文档用于说明当前项目中“游戏规则”在文档、配置文件、样例 JSON、解析代码和运行时规则引擎之间的实际组织方式。
+
+目标：
+
+- 说明规则设计从哪里开始
+- 说明公共配置和玩法配置如何分层
+- 说明样例配置、代码解析、运行时规则如何对应
+- 作为后续后台配置管理的架构基线
+
+---
+
+## 1. 总体原则
+
+当前项目采用的是“文档定义规则，配置承载规则，代码解析配置，规则引擎执行配置”的结构。
+
+可以概括为四句话：
+
+1. 玩法规则先在文档里定义
+2. 规则通过 JSON 配置文件表达
+3. 客户端解析配置生成运行态定义
+4. 规则引擎按运行态定义驱动游戏流程
+
+也就是说：
+
+**文档是设计源头，配置是规则载体，代码是执行层。**
+
+如果换一种更偏运行时的说法：
+
+- `MapEngine` 和页面壳子是骨架
+- 默认值层和规则层决定骨架怎么动
+- 配置像神经系统，把活动差异传进运行时
+- 遥测和反馈层负责把玩家状态再回流到界面
+
+---
+
+## 2. 当前分层结构
+
+当前规则体系分成 6 层。
+
+### 2.1 公共规则层
+
+位置：
+
+- [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
+- [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
+
+作用：
+
+- 定义系统共用能力有哪些
+- 定义公共字段、可选项和默认值
+- 作为所有玩法的公共配置全集
+
+这一层回答的是：
+
+- 系统支持哪些规则块
+- 系统有哪些字段
+- 这些字段默认怎么工作
+
+### 2.2 玩法设计层
+
+位置：
+
+- [程序默认规则基线](D:/dev/cmr-mini/doc/gameplay/程序默认规则基线.md)
+- [运行时编译层总表](D:/dev/cmr-mini/doc/gameplay/运行时编译层总表.md)
+- [玩法设计文档模板](D:/dev/cmr-mini/doc/gameplay/玩法设计文档模板.md)
+- [玩法构想方案](D:/dev/cmr-mini/doc/gameplay/玩法构想方案.md)
+- `doc/games/<游戏名称>/规则说明文档.md`
+- `doc/games/<游戏名称>/游戏说明文档.md`
+
+作用：
+
+- 定义客户端自身应该内建的默认行为
+- 定义某个玩法怎么玩
+- 定义局流程、状态机、计分、胜负、表现
+- 明确该玩法选用了哪些公共规则块
+
+这一层回答的是：
+
+- 这个玩法的目标是什么
+- 这个玩法如何开始、推进、结束
+- 这个玩法和系统公共能力的关系是什么
+
+### 2.3 玩法配置层
+
+位置：
+
+- `doc/games/<游戏名称>/最小配置模板.md`
+- `doc/games/<游戏名称>/最大配置模板.md`
+- `doc/games/<游戏名称>/全局配置项.md`
+- `doc/games/<游戏名称>/游戏配置项.md`
+- `event/*.json`
+
+作用：
+
+- 把玩法规则翻译为可执行配置
+- 明确这个玩法实际使用的公共字段子集
+- 给出最小可跑样例和较完整样例
+
+这一层回答的是：
+
+- 规则具体落到哪些字段
+- 哪些字段是系统默认
+- 哪些字段由玩法覆盖
+- 当前联调跑的是哪份样例配置
+
+### 2.4 配置解析层
+
+位置：
+
+- [remoteMapConfig.ts](D:/dev/cmr-mini/miniprogram/utils/remoteMapConfig.ts)
+- [courseToGameDefinition.ts](D:/dev/cmr-mini/miniprogram/game/content/courseToGameDefinition.ts)
+
+作用：
+
+- 读取远端或本地 JSON
+- 补齐模式默认值
+- 归一化为运行时使用的定义对象
+
+这一层回答的是：
+
+- 配置进入程序后如何被解释
+- 系统默认值何时注入
+- 不同玩法模式如何做差异化默认处理
+
+### 2.5 运行时默认与设置层
+
+位置：
+
+- [gameModeDefaults.ts](D:/dev/cmr-mini/miniprogram/game/core/gameModeDefaults.ts)
+- [systemSettingsState.ts](D:/dev/cmr-mini/miniprogram/game/core/systemSettingsState.ts)
+
+作用：
+
+- 统一维护玩法默认值
+- 统一维护设置页默认值
+- 明确哪些值持久化，哪些锁态不持久化
+- 为页面层和规则层提供同一套默认基线
+
+补充约束：
+
+- 设置值允许玩家修改并持久化
+- 设置锁态只由系统默认值和活动配置决定
+- 锁态不持久化，也不允许玩家在页面里切换
+- 锁态只在当前游戏配置运行生命周期内生效；本局结束或主动退出后失效
+
+### 2.6 运行时编译层
+
+位置：
+
+- [runtimeProfileCompiler.ts](D:/dev/cmr-mini/miniprogram/game/core/runtimeProfileCompiler.ts)
+- [运行时编译层总表](D:/dev/cmr-mini/doc/gameplay/运行时编译层总表.md)
+- [故障恢复机制](D:/dev/cmr-mini/doc/gameplay/故障恢复机制.md)
+
+作用：
+
+- 统一合并系统默认值、玩法默认值、活动配置和玩家设置
+- 产出页面、引擎和规则层可直接消费的运行时 profile
+- 逐步替代页面和引擎中分散的默认值判断
+
+当前进度：
+
+- `settings / telemetry / feedback` 已开始走编译层入口
+- 设置页大部分引擎型设置项已改成统一更新玩家设置，再由编译层回灌引擎
+- `settings` 当前已通过 `MapEngine.applyCompiledSettingsProfile(...)` 统一落地，不再由页面层散着逐项推送
+- `presentation` 和一部分 `game` 字段也已开始接入
+- `map` 也已开始接入地图底座和配置状态这组基础字段
+- `MapEngine.applyRemoteMapConfig(...)` 已开始退回为原始场地与资源入口
+
+这一层回答的是：
+
+- 程序默认值放在哪里
+- 玩家本地设置如何和系统默认值合并
+- 锁态为什么不能从历史缓存恢复
+- 为什么页面、引擎、规则不应再直接各自读原始配置
+
+### 2.7 故障恢复层
+
+位置：
+
+- [sessionRecovery.ts](D:/dev/cmr-mini/miniprogram/game/core/sessionRecovery.ts)
+- [map.ts](D:/dev/cmr-mini/miniprogram/pages/map/map.ts)
+- [mapEngine.ts](D:/dev/cmr-mini/miniprogram/engine/map/mapEngine.ts)
+
+作用：
+
+- 在对局进行中低频持久化轻量恢复快照
+- 在异常退出后提供“继续上一局 / 放弃上一局”入口
+- 只恢复核心运行态，不恢复瞬时 UI
+
+这一层回答的是：
+
+- 非正常退出后如何继续比赛
+- 为什么恢复只保留核心赛局状态
+- 为什么不尝试恢复白卡、答题卡和动效中间态
+
+### 2.8 运行时规则层
+
+位置：
+
+- [classicSequentialRule.ts](D:/dev/cmr-mini/miniprogram/game/rules/classicSequentialRule.ts)
+- [scoreORule.ts](D:/dev/cmr-mini/miniprogram/game/rules/scoreORule.ts)
+- [mapEngine.ts](D:/dev/cmr-mini/miniprogram/engine/map/mapEngine.ts)
+- [map.ts](D:/dev/cmr-mini/miniprogram/pages/map/map.ts)
+- [resultSummary.ts](D:/dev/cmr-mini/miniprogram/game/result/resultSummary.ts)
+- [telemetryRuntime.ts](D:/dev/cmr-mini/miniprogram/game/telemetry/telemetryRuntime.ts)
+- [playerTelemetryProfile.ts](D:/dev/cmr-mini/miniprogram/game/telemetry/playerTelemetryProfile.ts)
+
+作用：
+
+- 根据运行态定义执行状态流转
+- 响应 GPS、点击、打点、答题、结束等事件
+- 产出 HUD、反馈、结果页等最终体验
+- 明确区分可打目标、引导目标、HUD 目标和展示高亮目标
+
+这一层回答的是：
+
+- 玩家在游戏中的每一步如何被判定
+- 积分、答题、结束如何结算
+- 页面上显示什么、什么时候显示
+- 活动遥测默认值和玩家身体数据如何合并
+
+---
+
+## 3. 规则从设计到运行的链路
+
+当前实际链路如下：
+
+1. 在玩法文档里定义默认规则
+2. 在公共配置文档里定义字段与默认值
+3. 在玩法目录里确定该玩法使用哪些字段
+4. 在 `event/*.json` 中写出样例配置
+5. 由配置解析层读取 JSON 并注入模式默认值
+6. 由默认值与设置层补齐系统默认行为和玩家本地值
+7. 由规则引擎和 `MapEngine` 执行游戏逻辑
+8. 由结果页和 HUD 层展示最终状态
+
+其中遥测相关链路补充为：
+
+`系统默认值 -> 活动 telemetry 配置 -> 玩家线上身体数据 -> TelemetryRuntime -> HUD 第 2 页`
+
+设置相关链路补充为：
+
+`系统设置默认值 -> 玩家本地持久化值 -> 当前运行时锁态 -> map.ts / MapEngine`
+
+也可以简化成：
+
+`规则文档 -> 配置文档 -> 样例 JSON -> 配置解析 -> 规则引擎 -> 运行结果`
+
+当前已补一层轻量 smoke tests，用于卡住高风险回归：
+
+- 配置继承
+- 起点 / 终点规则
+- 积分赛自由打点
+- 锁态生命周期
+- 超时结束
+
+命令：
+
+- `npm run test:runtime-smoke`
+
+---
+
+## 4. 当前目录分工
+
+### 4.1 `doc/config`
+
+职责：
+
+- 公共配置全集
+- 公共字段字典
+- 公共模板
+- 发布和后台管理方案
+
+这一层不应该存放某个玩法自己的专属规则文档。
+
+### 4.2 `doc/gameplay`
+
+职责：
+
+- 通用玩法方法论
+- 玩法设计模板
+- 玩法构想和规则架构说明
+
+这一层不应该长期存放具体玩法的正式规则文档。
+
+### 4.3 `doc/games/<游戏名称>`
+
+职责：
+
+- 某个具体玩法的完整文档集合
+- 玩法说明
+- 规则说明
+- 最小 / 最大模板
+- 全局配置项子集
+- 游戏配置项子集
+
+这一层是具体玩法的唯一正式维护入口。
+
+### 4.4 `event/*.json`
+
+职责：
+
+- 当前可运行样例配置
+- 联调、验证、远端发布的直接输入
+
+这一层必须和玩法目录中的文档保持一致。
+
+---
+
+## 5. 当前已落地的玩法实例
+
+### 5.1 顺序打点
+
+正式文档入口：
+
+- [顺序打点/游戏说明文档](D:/dev/cmr-mini/doc/games/顺序打点/游戏说明文档.md)
+- [顺序打点/规则说明文档](D:/dev/cmr-mini/doc/games/顺序打点/规则说明文档.md)
+- [顺序打点/最小配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最小配置模板.md)
+- [顺序打点/最大配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最大配置模板.md)
+- [顺序打点/全局配置项](D:/dev/cmr-mini/doc/games/顺序打点/全局配置项.md)
+- [顺序打点/游戏配置项](D:/dev/cmr-mini/doc/games/顺序打点/游戏配置项.md)
+- [classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
+
+### 5.2 积分赛
+
+正式文档入口：
+
+- [积分赛/游戏说明文档](D:/dev/cmr-mini/doc/games/积分赛/游戏说明文档.md)
+- [积分赛/规则说明文档](D:/dev/cmr-mini/doc/games/积分赛/规则说明文档.md)
+- [积分赛/最小配置模板](D:/dev/cmr-mini/doc/games/积分赛/最小配置模板.md)
+- [积分赛/最大配置模板](D:/dev/cmr-mini/doc/games/积分赛/最大配置模板.md)
+- [积分赛/全局配置项](D:/dev/cmr-mini/doc/games/积分赛/全局配置项.md)
+- [积分赛/游戏配置项](D:/dev/cmr-mini/doc/games/积分赛/游戏配置项.md)
+- [score-o.json](D:/dev/cmr-mini/event/score-o.json)
+
+---
+
+## 6. 文档与代码同步约定
+
+后续每次规则变化，建议至少检查 4 层是否同步：
+
+1. 公共配置文档是否要补字段或默认值
+2. 对应玩法目录下的规则文档是否要改
+3. 对应 `event/*.json` 样例是否要改
+4. 配置解析和规则引擎是否要改
+
+如果只改了其中一层，就容易出现文档、配置、代码不一致。
+
+建议统一按下面顺序维护：
+
+1. 先改规则文档
+2. 再改配置文档和样例 JSON
+3. 再改解析代码和规则代码
+4. 最后回头核对结果页、HUD 和提示是否与文档一致
+
+---
+
+## 7. 和后续后台管理的关系
+
+当前本地项目里，规则主要由文档和样例 JSON 驱动。
+
+后续接后台后，分工仍然建议保持不变：
+
+- 玩法文档负责定义规则
+- 公共配置文档负责定义字段
+- 后台负责编辑、版本、校验、装配、发布
+- 客户端继续消费静态 JSON
+
+也就是说，后台是管理工具，不是规则源头。
+
+---
+
+## 8. 一句话总结
+
+当前这套实际架构可以概括为：
+
+**`doc/config` 管公共规则全集，`doc/games/<游戏名称>` 管玩法规则与配置子集，`event/*.json` 管可运行样例，客户端解析配置后交给规则引擎执行，并由轻量恢复层处理异常退出后的续局。**