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

2026-04-01 13:04:26 +08:00
parent 1635a11780
commit 3ef841ecc7
73 changed files with 8820 additions and 2122 deletions
--- a/doc/games/顺序打点/全局配置项.md
+++ b/doc/games/顺序打点/全局配置项.md
@@ -0,0 +1,20 @@
+# 顺序打点全局配置项
+
+本文档只列顺序打点对公共配置块的默认落点。完整字段定义仍以 [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md) 和 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md) 为准。
+
+| 名称 | 字段 | 顺序打点默认值 |
+| --- | --- | --- |
+| 开赛后显全场 | `game.visibility.revealFullPlayfieldAfterStartPunch` | `true` |
+| 必须先聚焦目标 | `game.punch.requiresFocusSelection` | `false` |
+| 最后点自动结束 | `game.session.autoFinishOnLastControl` | `false` |
+| 跳点启用 | `game.sequence.skip.enabled` | `true` |
+| 跳点半径 | `game.sequence.skip.radiusMeters` | `game.punch.radiusMeters * 2` |
+| 跳点确认 | `game.sequence.skip.requiresConfirm` | `false` |
+| 终点始终可选 | `game.finish.finishControlAlwaysSelectable` | `false` |
+| 默认控制点分值 | `game.scoring.defaultControlScore` | `1` |
+
+补充说明：
+
+- 开始点和结束点不弹题
+- 普通点默认自动进入 10 秒题卡
+- 答题时比赛继续计时
--- a/doc/games/顺序打点/最大配置模板.md
+++ b/doc/games/顺序打点/最大配置模板.md
@@ -0,0 +1,57 @@
+# 顺序打点最大配置模板
+
+本文档作为顺序打点的完整模板入口。当前项目仍维护一份共享全量模板：
+
+- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
+
+如果要为顺序打点新建一份“尽量全”的活动配置，建议至少覆盖这些块：
+
+```json
+{
+  "app": {},
+  "map": {},
+  "playfield": {
+    "kind": "course",
+    "source": {},
+    "CPRadius": 6,
+    "controlOverrides": {},
+    "legOverrides": {},
+    "metadata": {}
+  },
+  "game": {
+    "mode": "classic-sequential",
+    "session": {
+      "startManually": false,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": true,
+      "autoFinishOnLastControl": false
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5,
+      "requiresFocusSelection": false
+    },
+    "sequence": {
+      "skip": {
+        "enabled": true,
+        "radiusMeters": 10,
+        "requiresConfirm": false
+      }
+    },
+    "guidance": {},
+    "presentation": {},
+    "visibility": {},
+    "finish": {},
+    "telemetry": {},
+    "feedback": {}
+  },
+  "resources": {},
+  "debug": {}
+}
+```
+
+建议搭配阅读：
+
+- [规则说明文档](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)
--- a/doc/games/顺序打点/最小配置模板.md
+++ b/doc/games/顺序打点/最小配置模板.md
@@ -0,0 +1,232 @@
+# 顺序打点最小配置模板
+
+本文档提供一份 **顺序赛（`classic-sequential`）最小可跑配置模板**。
+
+目标：
+
+- 只保留顺序赛跑通所需的最少字段
+- 让测试尽量回到程序默认规则本身
+- 避免历史内容卡、H5 页面、样式覆盖继续干扰联调
+
+如果你关心“最小模板下系统到底默认怎么跑”，请优先配合阅读：
+
+- [顺序打点规则说明文档](D:/dev/cmr-mini/doc/games/顺序打点/规则说明文档.md)
+- [程序默认规则基线](D:/dev/cmr-mini/doc/gameplay/程序默认规则基线.md)
+
+---
+
+## 1. 最小模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.31",
+  "app": {
+    "id": "sample-classic-001",
+    "title": "顺序赛示例",
+    "locale": "zh-CN"
+  },
+  "map": {
+    "tiles": "../map/lxcb-001/tiles/",
+    "mapmeta": "../map/lxcb-001/tiles/meta.json",
+    "declination": 6.91,
+    "initialView": {
+      "zoom": 17
+    }
+  },
+  "playfield": {
+    "kind": "course",
+    "source": {
+      "type": "kml",
+      "url": "../kml/lxcb-001/10/c01.kml"
+    },
+    "CPRadius": 6,
+    "metadata": {
+      "title": "顺序赛路线示例",
+      "code": "classic-001"
+    }
+  },
+  "game": {
+    "mode": "classic-sequential"
+  }
+}
+```
+
+---
+
+## 2. 字段说明
+
+### `schemaVersion`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置结构版本
+- 当前建议值：`"1"`
+
+### `version`
+
+- 类型：`string`
+- 必填：是
+- 说明：配置版本号
+
+### `app.id`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动配置实例 ID
+
+### `app.title`
+
+- 类型：`string`
+- 必填：是
+- 说明：活动标题 / 比赛名称
+
+### `app.locale`
+
+- 类型：`string`
+- 必填：否
+- 说明：语言区域
+
+### `map.tiles`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图瓦片根路径
+
+### `map.mapmeta`
+
+- 类型：`string`
+- 必填：是
+- 说明：地图 meta 文件路径
+
+### `map.declination`
+
+- 类型：`number`
+- 必填：否
+- 说明：磁偏角，未填写时按程序默认值处理
+
+### `map.initialView.zoom`
+
+- 类型：`number`
+- 必填：否
+- 说明：初始缩放级别，未填写时按程序默认视口逻辑处理
+
+### `playfield.kind`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间对象类型
+- 顺序赛固定使用：`course`
+
+### `playfield.source.type`
+
+- 类型：`string`
+- 必填：是
+- 说明：空间底稿来源类型
+- 当前推荐值：`kml`
+
+### `playfield.source.url`
+
+- 类型：`string`
+- 必填：是
+- 说明：KML 文件路径
+
+### `playfield.CPRadius`
+
+- 类型：`number`
+- 必填：否
+- 说明：点位触发半径，未填写时按程序默认值处理
+
+### `playfield.metadata.title`
+
+- 类型：`string`
+- 必填：否
+- 说明：路线名称
+
+### `playfield.metadata.code`
+
+- 类型：`string`
+- 必填：否
+- 说明：路线编码
+
+### `game.mode`
+
+- 类型：`string`
+- 必填：是
+- 说明：玩法模式
+- 顺序赛固定值：`classic-sequential`
+
+### `game.*`
+
+- 类型：`object`
+- 必填：否
+- 说明：最小样例默认不依赖额外玩法覆盖字段
+- 备注：如需覆盖程序默认值，再补 `punch`、`sequence`、`guidance`、`finish` 等子块
+
+---
+
+## 3. 当前默认逻辑
+
+如果你只写本页最小模板，顺序赛会按程序默认规则运行。
+
+### 3.1 默认局流程
+
+- 进入游戏后默认只显示开始点
+- 系统默认提示玩家：需要先打开始点才正式开始比赛
+- 未打开始点前，普通控制点和终点不生效
+- 首次成功打开始点后：
+  - 正式开始比赛
+  - 初始化本局数据
+  - 开始计时
+  - 显示全部普通控制点、终点和腿线
+  - 默认只给出“比赛开始”短反馈，并同步更新引导提示和 HUD
+  - 最小模板下默认不弹开始白色内容卡
+- 最小模板下，点击检查点默认不弹详情卡
+- 普通控制点默认允许跳点
+- 普通控制点成功打点后默认：
+  - 先得 `1` 分基础分
+  - 默认不弹题
+  - 如需答题卡，需显式配置对应点位的 `quiz` CTA
+- 开始点和结束点默认不弹题，只弹提示信息
+- 成功打结束点后：
+  - 停止计时
+  - 给出完成短反馈
+  - 直接进入默认成绩结算页
+  - 默认不再额外叠加终点白色内容卡
+- 白色内容卡默认改为显式配置启用；只有某个点位明确配置 `autoPopup = true` 时，完成该点后才会先弹白卡
+
+### 3.2 默认规则参数
+
+- `map.declination`
+  - 没配时默认按 `0`
+- `map.initialView.zoom`
+  - 没配时由客户端初始视口逻辑接管
+- `playfield.CPRadius`
+  - 没配时按客户端内置值处理
+- `game.session.*`
+  - 默认非手动开始
+  - 默认要求起点打卡
+  - 默认要求终点打卡
+  - 默认不在最后一个普通点自动结束
+- `game.sequence.skip.*`
+  - 默认启用跳点
+  - 默认跳点半径 = 打点半径的 2 倍
+  - 默认不需要二次确认
+- `game.guidance.*`
+  - 默认显示路线腿线
+  - 默认显示腿线动效
+  - 默认不允许手动聚焦选点
+- `game.visibility.revealFullPlayfieldAfterStartPunch`
+  - 默认按 `true` 处理
+- `game.finish.finishControlAlwaysSelectable`
+  - 默认按 `false` 处理
+
+---
+
+## 4. 当前样例说明
+
+当前仓库中的 [classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json) 已按这套最小测试口径收敛，只保留地图、场地和玩法标识，不再附带历史测试内容卡、H5 页面和样式覆盖。
+
+如果要查看公共完整字段，请继续参考：
+
+- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
--- a/doc/games/顺序打点/游戏说明文档.md
+++ b/doc/games/顺序打点/游戏说明文档.md
@@ -0,0 +1,33 @@
+# 顺序打点游戏说明文档
+
+本文档作为 `classic-sequential` 的目录入口，用来统一说明本玩法文档放在哪里、分别看什么。
+
+## 1. 玩法定位
+
+- 玩法名称：顺序打点
+- 模式标识：`classic-sequential`
+- 核心特征：按顺序推进，允许跳点，起终点必须打卡
+- 当前默认：普通点基础分 `1`，答对题卡再得 `1` 分
+
+## 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)
+  顺序打点独有或强相关字段
+
+## 3. 运行样例
+
+- [classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
+
+## 4. 关联公共文档
+
+- [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+- [全局规则与配置维度清单](D:/dev/cmr-mini/doc/config/全局规则与配置维度清单.md)
+- [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
--- a/doc/games/顺序打点/游戏配置项.md
+++ b/doc/games/顺序打点/游戏配置项.md
@@ -0,0 +1,358 @@
+# 顺序打点游戏配置项
+
+本文档用于汇总当前系统对 `classic-sequential` 的**已支持可配置项**，便于产品、客户端、服务端、后台录入和联调统一对照。
+
+目标：
+
+- 列出顺序打点当前可配置的字段名
+- 说明每个字段的作用
+- 说明字段可选项或取值范围
+- 标注推荐默认值或当前默认逻辑
+
+说明：
+
+- 本文档只聚焦 `classic-sequential`
+- 以当前实现和现有文档口径为准
+- 如果你需要看跨玩法的完整字段字典，请继续参考 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md)
+
+---
+
+## 1. 顶层结构
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.31",
+  "app": {},
+  "map": {},
+  "playfield": {},
+  "game": {},
+  "resources": {},
+  "debug": {}
+}
+```
+
+---
+
+## 2. 顶层字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `schemaVersion` | 配置结构版本 | 当前建议：`"1"` | 建议固定写 `"1"` |
+| `version` | 当前配置内容版本号 | 任意版本字符串，例如日期版号 | 建议按发布日期维护 |
+| `app` | 活动级基础信息 | `object` | 必填 |
+| `map` | 地图底座信息 | `object` | 必填 |
+| `playfield` | 场地对象、路线和点位内容覆盖 | `object` | 必填 |
+| `game` | 顺序打点规则与局流程 | `object` | 必填 |
+| `resources` | 资源 profile 引用 | `object` | 选填 |
+| `debug` | 调试开关 | `object` | 选填 |
+
+---
+
+## 3. `app`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `app.id` | 活动或配置实例 ID | 任意字符串 | 建议全局唯一 |
+| `app.title` | 活动标题 / 比赛名称 | 任意字符串 | 建议必填 |
+| `app.locale` | 语言环境 | 当前常用：`zh-CN` | 默认建议：`zh-CN` |
+
+---
+
+## 4. `map`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `map.tiles` | 瓦片根路径 | 路径字符串 | 必填 |
+| `map.mapmeta` | 地图元数据路径 | 路径字符串 | 必填 |
+| `map.declination` | 磁偏角 | `number` | 未配置时按 `0` 处理 |
+| `map.initialView.zoom` | 初始缩放级别 | `number` | 默认由客户端初始视口逻辑接管，建议值 `17` |
+
+---
+
+## 5. `playfield`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `playfield.kind` | 场地对象类型 | 顺序打点固定使用：`course` | 顺序打点建议固定 `course` |
+| `playfield.source.type` | 场地来源类型 | 当前支持：`kml` | 建议固定 `kml` |
+| `playfield.source.url` | KML 路径 | 路径字符串 | 必填 |
+| `playfield.CPRadius` | 地图上控制点绘制半径 | `number` | 建议默认值：`6` |
+| `playfield.metadata.title` | 路线标题 | 任意字符串 | 选填 |
+| `playfield.metadata.code` | 路线编码 | 任意字符串 | 选填 |
+
+---
+
+## 6. `playfield.controlOverrides`
+
+`playfield.controlOverrides` 用于对指定起点、普通控制点、终点做内容和样式覆盖。
+
+### 6.1 Key 命名
+
+| Key 模式 | 作用 |
+| --- | --- |
+| `start-1` | 起点 |
+| `control-1`、`control-2`、`control-3` | 普通控制点 |
+| `finish-1` | 终点 |
+
+### 6.2 内容与交互字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `playfield.controlOverrides.<key>.template` | 原生内容卡模板 | `minimal` `story` `focus` | 起点/终点建议 `focus`，普通点建议 `story` |
+| `playfield.controlOverrides.<key>.title` | 打点后自动弹出的标题 | 任意字符串 | 未配置时走默认文案 |
+| `playfield.controlOverrides.<key>.body` | 打点后自动弹出的正文 | 任意字符串 | 未配置时走默认文案 |
+| `playfield.controlOverrides.<key>.clickTitle` | 点击点位时弹出的标题 | 任意字符串 | 最小模板下默认关闭，需显式配置 |
+| `playfield.controlOverrides.<key>.clickBody` | 点击点位时弹出的正文 | 任意字符串 | 最小模板下默认关闭，需显式配置 |
+| `playfield.controlOverrides.<key>.autoPopup` | 打点后是否自动弹内容卡 | `true` / `false` | 默认 `true`；自动打点模式下不自动弹内容卡；普通控制点默认题卡仍按玩法规则自动进入 |
+| `playfield.controlOverrides.<key>.once` | 自动内容是否本局只展示一次 | `true` / `false` | 默认 `false` |
+| `playfield.controlOverrides.<key>.priority` | 内容优先级 | `number` | 普通点默认 `1`，终点默认 `2` |
+
+### 6.3 H5 / 原生体验承载字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `playfield.controlOverrides.<key>.contentExperience.type` | 打点后内容承载方式 | `native` `h5` | 当前支持两种 |
+| `playfield.controlOverrides.<key>.contentExperience.url` | 打点后 H5 地址 | URL 字符串 | 仅 `type = "h5"` 时生效 |
+| `playfield.controlOverrides.<key>.contentExperience.bridge` | 打点后 H5 bridge 版本 | 当前建议：`content-v1` | 默认建议：`content-v1` |
+| `playfield.controlOverrides.<key>.contentExperience.presentation` | 打点后 H5 展示形态 | `sheet` `dialog` `fullscreen` | 默认建议：`sheet` |
+| `playfield.controlOverrides.<key>.clickExperience.type` | 点击内容承载方式 | `native` `h5` | 当前支持两种 |
+| `playfield.controlOverrides.<key>.clickExperience.url` | 点击 H5 地址 | URL 字符串 | 仅 `type = "h5"` 时生效 |
+| `playfield.controlOverrides.<key>.clickExperience.bridge` | 点击 H5 bridge 版本 | 当前建议：`content-v1` | 默认建议：`content-v1` |
+| `playfield.controlOverrides.<key>.clickExperience.presentation` | 点击 H5 展示形态 | `sheet` `dialog` `fullscreen` | 默认建议：`sheet` |
+
+### 6.4 点位样式覆盖字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `playfield.controlOverrides.<key>.pointStyle` | 单点样式覆盖 | `classic-ring` `solid-dot` `double-ring` `badge` `pulse-core` | 未配置时回退到玩法样式 |
+| `playfield.controlOverrides.<key>.pointColorHex` | 单点颜色覆盖 | 十六进制颜色字符串 | 例如 `#27ae60` |
+| `playfield.controlOverrides.<key>.pointSizeScale` | 单点尺寸倍率 | 建议 `0.6 ~ 1.4` | 默认 `1` |
+| `playfield.controlOverrides.<key>.pointAccentRingScale` | 单点强调环倍率 | 建议 `1.0 ~ 1.6` | 未配置时回退到玩法样式 |
+| `playfield.controlOverrides.<key>.pointGlowStrength` | 单点光晕强度 | 建议 `0 ~ 1` | 默认 `0` |
+| `playfield.controlOverrides.<key>.pointLabelScale` | 单点标签字号倍率 | 建议 `0.7 ~ 1.3` | 默认 `1` |
+| `playfield.controlOverrides.<key>.pointLabelColorHex` | 单点标签颜色覆盖 | 十六进制颜色字符串 | 例如 `#ffffff` |
+
+---
+
+## 7. `playfield.legOverrides`
+
+`playfield.legOverrides` 用于对指定腿线做局部样式覆盖。
+
+### 7.1 Key 命名
+
+| Key 模式 | 作用 |
+| --- | --- |
+| `leg-1`、`leg-2`、`leg-3` | 指定路线腿段 |
+
+### 7.2 字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `playfield.legOverrides.<key>.style` | 局部腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 未配置时回退到玩法样式 |
+| `playfield.legOverrides.<key>.colorHex` | 局部腿线颜色 | 十六进制颜色字符串 | 例如 `#27ae60` |
+| `playfield.legOverrides.<key>.widthScale` | 局部腿线宽度倍率 | `number` | 选填 |
+| `playfield.legOverrides.<key>.glowStrength` | 局部腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
+
+---
+
+## 8. `game`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.mode` | 玩法类型 | 顺序打点固定：`classic-sequential` | 建议固定写死 |
+| `game.rulesVersion` | 规则版本 | 任意字符串，当前建议 `1` | 建议随规则迭代维护 |
+
+---
+
+## 9. `game.session`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.session.startManually` | 是否手动开始 | `true` / `false` | 顺序打点默认 `false`，通过起点打卡正式开赛 |
+| `game.session.requiresStartPunch` | 是否必须打起点 | `true` / `false` | 顺序打点默认 `true` |
+| `game.session.requiresFinishPunch` | 是否必须打终点 | `true` / `false` | 顺序打点默认 `true` |
+| `game.session.autoFinishOnLastControl` | 最后一个普通控制点完成后是否自动结束 | `true` / `false` | 顺序打点默认 `false` |
+| `game.session.maxDurationSec` | 最大比赛时长 | `number` | 建议默认 `5400` |
+
+---
+
+## 10. `game.punch`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.punch.policy` | 打点策略 | `enter-confirm` `enter` | 默认 `enter-confirm` |
+| `game.punch.radiusMeters` | 打点判定半径 | `number` | 默认建议 `5` |
+| `game.punch.requiresFocusSelection` | 是否必须先聚焦目标再打点 | `true` / `false` | 顺序打点默认 `false` |
+
+---
+
+## 11. `game.sequence.skip`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.sequence.skip.enabled` | 是否允许跳点 | `true` / `false` | 顺序打点默认 `true` |
+| `game.sequence.skip.radiusMeters` | 跳点判定半径 | `number` | 顺序打点默认 `game.punch.radiusMeters * 2` |
+| `game.sequence.skip.requiresConfirm` | 跳点是否需要确认 | `true` / `false` | 顺序打点默认 `false` |
+
+---
+
+## 12. `game.guidance`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.guidance.showLegs` | 是否显示路线腿线 | `true` / `false` | 顺序打点默认 `true` |
+| `game.guidance.legAnimation` | 是否开启腿线动画 | `true` / `false` | 顺序打点默认 `true` |
+| `game.guidance.allowFocusSelection` | 是否允许地图点击选点 | `true` / `false` | 顺序打点默认 `false` |
+
+---
+
+## 13. `game.visibility`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.visibility.revealFullPlayfieldAfterStartPunch` | 起点打卡后是否显示完整路线与控制点 | `true` / `false` | 顺序打点默认 `true` |
+
+---
+
+## 14. `game.finish`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.finish.finishControlAlwaysSelectable` | 终点是否始终可生效 | `true` / `false` | 顺序打点默认 `false`，默认要求中间点都已“成功”或“跳过” |
+
+---
+
+## 15. `game.telemetry.heartRate`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.telemetry.heartRate.age` | 年龄 | `number` | 建议默认 `30` |
+| `game.telemetry.heartRate.restingHeartRateBpm` | 静息心率 | `number` | 建议默认 `62` |
+| `game.telemetry.heartRate.userWeightKg` | 体重（kg） | `number` | 建议默认 `65` |
+
+---
+
+## 16. `game.feedback`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.feedback.audioProfile` | 音效反馈配置档 | `string` | 默认 `default` |
+| `game.feedback.hapticsProfile` | 震动反馈配置档 | `string` | 默认 `default` |
+| `game.feedback.uiEffectsProfile` | UI 动效配置档 | `string` | 默认 `default` |
+
+---
+
+## 17. `game.presentation.sequential.controls`
+
+以下字段分别作用于不同控制点状态：`default`、`current`、`completed`、`skipped`、`start`、`finish`。
+
+### 17.1 状态节点
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.presentation.sequential.controls.default` | 普通未完成控制点样式 | `object` | 建议使用传统定向紫红色 |
+| `game.presentation.sequential.controls.current` | 当前目标点样式 | `object` | 建议强化动效和光晕 |
+| `game.presentation.sequential.controls.completed` | 已完成点样式 | `object` | 默认建议灰色态 |
+| `game.presentation.sequential.controls.skipped` | 已跳过点样式 | `object` | 默认建议橙色态 |
+| `game.presentation.sequential.controls.start` | 起点样式 | `object` | 建议带明显开赛强调 |
+| `game.presentation.sequential.controls.finish` | 终点样式 | `object` | 建议带明显收尾强调 |
+
+### 17.2 每个状态对象内可配置字段
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `<state>.style` | 点位样式 | `classic-ring` `solid-dot` `double-ring` `badge` `pulse-core` | 按状态选择 |
+| `<state>.colorHex` | 点位主色 | 十六进制颜色字符串 | 例如 `#cc006b` |
+| `<state>.sizeScale` | 点位尺寸倍率 | `number` | 选填 |
+| `<state>.accentRingScale` | 强调环倍率 | `number` | 选填 |
+| `<state>.glowStrength` | 光晕强度 | 建议 `0 ~ 1` | 选填 |
+| `<state>.labelScale` | 标签尺寸倍率 | `number` | 选填 |
+| `<state>.labelColorHex` | 标签颜色 | 十六进制颜色字符串 | 选填 |
+
+---
+
+## 18. `game.presentation.sequential.legs`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.presentation.sequential.legs.default.style` | 默认腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 建议顺序打点使用 `classic-leg` |
+| `game.presentation.sequential.legs.default.colorHex` | 默认腿线主色 | 十六进制颜色字符串 | 建议传统定向紫红色 |
+| `game.presentation.sequential.legs.default.widthScale` | 默认腿线宽度倍率 | `number` | 选填 |
+| `game.presentation.sequential.legs.default.glowStrength` | 默认腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
+| `game.presentation.sequential.legs.completed.style` | 已完成腿线样式 | `classic-leg` `dashed-leg` `glow-leg` `progress-leg` | 建议弱化样式 |
+| `game.presentation.sequential.legs.completed.colorHex` | 已完成腿线颜色 | 十六进制颜色字符串 | 建议灰色系 |
+| `game.presentation.sequential.legs.completed.widthScale` | 已完成腿线宽度倍率 | `number` | 选填 |
+| `game.presentation.sequential.legs.completed.glowStrength` | 已完成腿线光晕强度 | 建议 `0 ~ 1` | 选填 |
+
+---
+
+## 19. `game.presentation.track`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.presentation.track.mode` | 轨迹显示模式 | `none` `tail` `full` | 顺序打点默认建议 `full` |
+| `game.presentation.track.style` | 轨迹风格 | `classic` `neon` | 当前默认 `neon` |
+| `game.presentation.track.tailLength` | 拖尾长度档位 | `short` `medium` `long` | 仅 `tail` 模式重点使用 |
+| `game.presentation.track.colorPreset` | 轨迹预设色盘 | `mint` `cyan` `sky` `blue` `violet` `pink` `orange` `yellow` | 未显式配置颜色时可走预设 |
+| `game.presentation.track.tailMeters` | 拖尾长度（米） | `number` | 可覆盖 `tailLength` |
+| `game.presentation.track.tailMaxSeconds` | 拖尾时间窗口（秒） | `number` | 选填 |
+| `game.presentation.track.fadeOutWhenStill` | 静止后是否淡出 | `true` / `false` | 选填 |
+| `game.presentation.track.stillSpeedKmh` | 静止判定速度阈值 | `number` | 选填 |
+| `game.presentation.track.fadeOutDurationMs` | 静止淡出时长 | `number` | 选填 |
+| `game.presentation.track.colorHex` | 轨迹主色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
+| `game.presentation.track.headColorHex` | 轨迹头部高亮色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
+| `game.presentation.track.widthPx` | 轨迹基础宽度 | `number` | 选填 |
+| `game.presentation.track.headWidthPx` | 轨迹头部宽度 | `number` | 选填 |
+| `game.presentation.track.glowStrength` | 轨迹光晕强度 | 建议 `0 ~ 1` | 选填 |
+
+---
+
+## 20. `game.presentation.gpsMarker`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `game.presentation.gpsMarker.visible` | 是否显示 GPS 点 | `true` / `false` | 默认 `true` |
+| `game.presentation.gpsMarker.style` | GPS 点基础样式 | `dot` `beacon` `disc` `badge` | 当前默认 `beacon` |
+| `game.presentation.gpsMarker.size` | GPS 点尺寸档位 | `small` `medium` `large` | 当前默认 `medium` |
+| `game.presentation.gpsMarker.colorPreset` | GPS 点预设色盘 | `mint` `cyan` `sky` `blue` `violet` `pink` `orange` `yellow` | 当前默认 `cyan` |
+| `game.presentation.gpsMarker.colorHex` | GPS 点主色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
+| `game.presentation.gpsMarker.ringColorHex` | GPS 点外环颜色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
+| `game.presentation.gpsMarker.indicatorColorHex` | 朝向指示颜色 | 十六进制颜色字符串 | 未配置时回退到 `colorPreset` |
+| `game.presentation.gpsMarker.showHeadingIndicator` | 是否显示朝向小三角 | `true` / `false` | 默认 `true` |
+| `game.presentation.gpsMarker.animationProfile` | GPS 点动画 profile | `minimal` `dynamic-runner` `warning-reactive` | 当前默认 `dynamic-runner` |
+| `game.presentation.gpsMarker.logoUrl` | 中心贴片 logo 地址 | URL 字符串 | 选填 |
+| `game.presentation.gpsMarker.logoMode` | logo 嵌入方式 | `center-badge` | 当前支持该值 |
+
+---
+
+## 21. `resources`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `resources.audioProfile` | 音效资源档 | `string` | 默认 `default` |
+| `resources.contentProfile` | 内容资源档 | `string` | 默认 `default` |
+| `resources.themeProfile` | 主题资源档 | `string` | 默认 `default-race` |
+
+---
+
+## 22. `debug`
+
+| 字段 | 作用 | 可选项 / 取值 | 默认 / 备注 |
+| --- | --- | --- | --- |
+| `debug.allowModeSwitch` | 是否允许玩法切换调试 | `true` / `false` | 默认 `false` |
+| `debug.allowMockInput` | 是否允许模拟输入 | `true` / `false` | 默认 `false` |
+| `debug.allowSimulator` | 是否允许模拟器 | `true` / `false` | 默认 `false` |
+
+---
+
+## 23. 推荐阅读顺序
+
+如果你是为了推进顺序打点开发，建议按这个顺序阅读：
+
+1. [顺序打点规则说明文档](D:/dev/cmr-mini/doc/games/顺序打点/规则说明文档.md)
+2. 本文档
+3. [顺序打点最小配置模板](D:/dev/cmr-mini/doc/games/顺序打点/最小配置模板.md)
+4. [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
+5. [顺序赛样例配置](D:/dev/cmr-mini/event/classic-sequential.json)
+
--- a/doc/games/顺序打点/规则说明文档.md
+++ b/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`
+
+其余流程默认按本文档执行。
+
+也就是说，本文档定义的是：
+
+- 最小模板下的系统默认局流程
+- 后续配置化扩展前的默认产品行为
+- 顺序赛样例配置和实现验收时的基准口径
+