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

doc/gameplay/玩法设计文档模板.md

@@ -0,0 +1,411 @@
+# 玩法设计文档模板
+
+本文档用于定义后续所有玩法设计文档的**统一写法**，保证玩法规则、全局规则块、配置落点和最小样例能够一起沉淀，为后续 JSON 配置管理和后台装配提供稳定输入。
+
+目标：
+
+- 统一玩法设计文档结构
+- 避免只写“玩法创意”，不写“配置落点”
+- 让后续玩法都能自然接到配置文件和后台管理方案
+
+说明：
+
+- 本文档是模板，不是具体玩法规则
+- 后期 JSON 配置管理以专门后台方案承接
+- 本文档负责沉淀“设计输入”
+- 后台方案负责沉淀“编辑、版本、发布、装配”
+
+建议配合阅读：
+
+- [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
+- [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+- [后台配置管理方案V2](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
+
+---
+
+## 1. 使用方式
+
+后续每新增一个玩法，都建议新建一份玩法文档，并按本模板完整填写。
+
+推荐存放方式：
+
+- `doc/games/<游戏名称>/游戏说明文档.md`
+- `doc/games/<游戏名称>/规则说明文档.md`
+- `doc/games/<游戏名称>/最小配置模板.md`
+- `doc/games/<游戏名称>/最大配置模板.md`
+- `doc/games/<游戏名称>/全局配置项.md`
+- `doc/games/<游戏名称>/游戏配置项.md`
+
+如果玩法还处于发散阶段，可以先写“构想方案”；  
+一旦进入可开发阶段，就应该补齐本模板里的正式章节。
+
+---
+
+## 2. 标准章节清单
+
+后续每个玩法设计文档，建议至少包含以下章节：
+
+1. 文档定位
+2. 一句话规则
+3. 设计目标
+4. 适用范围
+5. 局流程
+6. 核心对象模型
+7. 判定与状态机
+8. 计分与胜负规则
+9. 全局规则块选型
+10. 配置落点
+11. 最小可跑配置样例
+12. 验收清单
+13. 后续扩展点
+
+---
+
+## 3. 模板正文
+
+以下为推荐模板正文，可直接复制新建玩法文档后填写。
+
+---
+
+# `玩法名称`
+
+## 1. 文档定位
+
+本文档用于定义 `玩法模式标识` 的正式规则、默认行为、配置落点和最小可跑样例。
+
+当前阶段目标：
+
+- 说明玩法怎么玩
+- 说明系统如何判定
+- 说明配置文件如何承载
+- 说明哪些沿用系统默认，哪些需要玩法覆盖
+
+---
+
+## 2. 一句话规则
+
+请用一句话写清：
+
+- 玩家要做什么
+- 怎样推进
+- 怎样结束
+- 怎样赢 / 怎样结算
+
+示例：
+
+> 玩家需要按顺序完成控制点打卡，允许跳点；普通点打卡后回答限时数学题获取奖励分，打完终点后结算成绩。
+
+---
+
+## 3. 设计目标
+
+建议至少说明：
+
+- 这个玩法的核心乐趣是什么
+- 它和已有玩法的主要差异是什么
+- 它优先验证哪种系统能力
+
+建议回答：
+
+- 是否偏竞技
+- 是否偏探索
+- 是否偏轻量复玩
+- 是否偏实时压力
+
+---
+
+## 4. 适用范围
+
+建议至少说明：
+
+- 适用于单人还是多人
+- 是否依赖真实 GPS
+- 是否依赖模拟器
+- 是否依赖心率等遥测能力
+- 是否依赖路线型场地还是对象集型场地
+
+建议落成明确语句：
+
+- 支持：`单人 / 多人`
+- 输入依赖：`GPS / 心率 / 模拟输入`
+- 场地类型：`course / control-set / region-set / object-set`
+
+---
+
+## 5. 局流程
+
+建议按时间顺序写完整流程：
+
+### 5.1 进入游戏
+
+- 初始看到什么
+- 哪些对象显示，哪些隐藏
+- 是否立即开始计时
+- 是否先弹提示
+
+### 5.2 正式开始
+
+- 什么事件触发正式开局
+- 是否初始化数据
+- 是否显示全图 / 全路线
+- 是否弹开始提示
+
+### 5.3 进行中推进
+
+- 玩家如何推进
+- 当前目标如何变化
+- 是否允许跳点 / 切目标 / 自由选点
+- 进行中有哪些关键反馈
+
+### 5.4 结束
+
+- 什么条件触发结束
+- 是否立即停止计时
+- 是否弹结束提示
+- 是否进入结算页
+
+---
+
+## 6. 核心对象模型
+
+建议列清玩法运行依赖的对象类型。
+
+示例格式：
+
+| 对象类型 | 作用 | 是否必需 | 备注 |
+| --- | --- | --- | --- |
+| `start` | 起始触发点 | 是 | 用于正式开赛 |
+| `control` | 普通推进目标 | 是 | 可按玩法扩展属性 |
+| `finish` | 结束点 | 视玩法而定 | 用于结束比赛 |
+| `bonus` | 奖励对象 | 否 | 可选 |
+| `danger-zone` | 危险区域 | 否 | 可选 |
+
+还建议说明：
+
+- 对象来源于 `KML` 还是运行时生成
+- 对象是静态的还是动态变化的
+- 对象是否有状态切换
+
+---
+
+## 7. 判定与状态机
+
+### 7.1 局状态
+
+建议明确列出局状态，例如：
+
+1. `ready`
+2. `running`
+3. `paused`
+4. `finished`
+5. `settled`
+
+### 7.2 关键判定
+
+建议逐条写清：
+
+- 打点成功判定
+- 跳点判定
+- 得分判定
+- 失败判定
+- 完赛判定
+
+### 7.3 状态切换条件
+
+建议写成表：
+
+| 当前状态 | 触发事件 | 下一状态 | 备注 |
+| --- | --- | --- | --- |
+| `ready` | 起点打卡成功 | `running` | 正式开始计时 |
+| `running` | 结束条件满足且终点打卡 | `finished` | 停止计时 |
+| `finished` | 关闭结束提示 | `settled` | 进入结算页 |
+
+---
+
+## 8. 计分与胜负规则
+
+建议明确：
+
+- 基础分怎么来
+- 奖励分怎么来
+- 扣分怎么来
+- 跳过点如何处理
+- 最终成绩显示哪些指标
+
+推荐格式：
+
+| 规则项 | 说明 | 默认值 | 备注 |
+| --- | --- | --- | --- |
+| 基础分 | 成功打点获得 | `1` | 示例 |
+| 奖励分 | 答题答对获得 | `1` | 示例 |
+| 跳过点得分 | 是否得分 | `0` | 示例 |
+| 结算指标 | 总用时 / 总分 / 成功点数 | - | 示例 |
+
+如果玩法没有积分，也要写清：
+
+- 胜负依据是什么
+- 排名依据是什么
+- 是否只有完赛状态
+
+---
+
+## 9. 全局规则块选型
+
+本节必须回答“这个玩法用了哪些全局能力块，以及默认选型是什么”。
+
+建议按下表填写：
+
+| 规则块 | 是否使用 | 选型 / 配置方向 | 默认值策略 | 备注 |
+| --- | --- | --- | --- | --- |
+| 地图底座 | 是 | 自定义地图 + KML | 沿用系统默认 |  |
+| 点位表现 | 是 | 传统定向紫红系 | 可局部覆盖 |  |
+| 腿线表现 | 是 | `classic-leg` + 动效 | 顺序类沿用默认 |  |
+| 轨迹表现 | 是 | `full` / `tail` / `none` | 玩法指定 |  |
+| 定位点表现 | 是 | `beacon` / `dot` 等 | 沿用系统默认或玩法覆盖 |  |
+| 引导显示 | 是 | 是否显示腿线、是否允许选点 | 玩法指定 |  |
+| 可见性策略 | 是 | 开局隐藏 / 起点后全显 | 玩法指定 |  |
+| 内容体验 | 否 / 是 | 原生 / H5 / 不启用 | 玩法指定 |  |
+| 反馈系统 | 是 | 音效 / 震动 / UI 档位 | 玩法指定 |  |
+| 遥测参数 | 否 / 是 | 是否用心率 | 沿用默认或玩法覆盖 |  |
+| 调试能力 | 是 | 是否开放模拟器 | 开发期指定 |  |
+
+本节的目的不是重复字段字典，而是明确：
+
+- 这个玩法到底用了哪些公共块
+- 哪些沿用默认
+- 哪些要做玩法覆盖
+
+---
+
+## 10. 配置落点
+
+本节用于把规则翻译成配置结构。
+
+建议写成表：
+
+| 设计项 | 配置落点 | 是否已有字段 | 默认值 | 是否建议后台表单化 |
+| --- | --- | --- | --- | --- |
+| 起点后显示全路线 | `game.visibility.revealFullPlayfieldAfterStartPunch` | 是 | `true` | 是 |
+| 跳点开关 | `game.sequence.skip.enabled` | 是 | `true` | 是 |
+| 答题倒计时 | `待补字段` | 否 | `10` | 先走 JSON 区 |
+| 目标点样式 | `game.presentation.sequential.controls.current` | 是 | 玩法指定 | 可后续表单化 |
+
+这里建议把字段分成两类：
+
+### 10.1 稳定字段
+
+适合后续做后台正式表单：
+
+- 模式
+- 半径
+- 是否必须起点 / 终点
+- 是否显示腿线
+- 是否显示轨迹
+- 是否允许跳点
+- 是否启用内容体验
+
+### 10.2 易变字段
+
+更适合先放 JSON 编辑区：
+
+- 实验性计分细则
+- 特殊答题规则
+- 视觉实验参数
+- 单点特殊表现
+- 复杂状态映射
+
+本节要和后续后台管理方案衔接，避免字段落点混乱。
+
+---
+
+## 11. 最小可跑配置样例
+
+本节建议给出一个最小可跑 JSON 样例。
+
+要求：
+
+- 只保留当前玩法最关键字段
+- 能作为联调和测试入口
+- 和规则说明保持一致
+
+建议结构：
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.31",
+  "app": {},
+  "map": {},
+  "playfield": {},
+  "game": {},
+  "resources": {},
+  "debug": {}
+}
+```
+
+如果已有运行中的 `event/*.json`，应在本节明确引用对应样例。
+
+---
+
+## 12. 验收清单
+
+建议至少覆盖：
+
+| 验收项 | 是否通过 | 备注 |
+| --- | --- | --- |
+| 开局流程与文档一致 |  |  |
+| 打点判定与文档一致 |  |  |
+| 计分规则与文档一致 |  |  |
+| 点位表现与文档一致 |  |  |
+| 轨迹与定位点表现一致 |  |  |
+| 结算页指标与文档一致 |  |  |
+| 样例配置可跑通 |  |  |
+| 文档与配置字段口径一致 |  |  |
+
+---
+
+## 13. 后续扩展点
+
+本节建议专门写：
+
+- 哪些能力当前先不做
+- 哪些字段未来可能配置化
+- 哪些地方后续会交给后台表单化管理
+
+示例：
+
+- 第一阶段先固定答题倒计时为 `10` 秒，后续再配置化
+- 第一阶段先固定基础分 / 奖励分，后续再补 `game.scoring` 细项
+- 第一阶段样式先走 profile，后续再细化到按状态表单配置
+
+---
+
+## 14. 文档产出要求
+
+后续新增一个正式玩法文档时，建议至少同步产出以下内容：
+
+1. 一份玩法规则文档
+2. 一份对应最小样例配置
+3. 如有新增公共能力，更新 [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
+4. 如有新增字段，更新 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+
+---
+
+## 15. 和后台方案的关系
+
+后期 JSON 配置文档建议通过专门后台管理，但要注意分工：
+
+- 玩法文档：
+  负责定义规则、默认值、配置落点、最小样例
+- 配置字典：
+  负责定义字段含义、可选项和默认值
+- 后台方案：
+  负责对象、版本、校验、装配、发布
+
+也就是说：
+
+**玩法文档是“设计源头”，后台系统是“管理和发布工具”。**
+
+不要让后台方案反过来决定玩法规则结构。
+
+