整理文档并接入 H5 体验测试链路

2026-03-27 15:36:27 +08:00
parent 0e025c3426
commit 0e0a724025
55 changed files with 4177 additions and 55 deletions
--- a/doc/config-default-template.md
+++ b/doc/config-default-template.md
@@ -0,0 +1,415 @@
+# 默认配置模板文档（当前实现版）
+
+本文档提供一份 **当前客户端可直接使用的默认配置模板**。  
+目标是：
+
+- 给服务端/后台一个稳定的起步模板
+- 保证即使只填最少字段，也能正常跑起来
+- 随开发持续补充和维护
+
+说明：
+
+- 本模板优先保证“可运行”
+- 高级字段可以逐步补
+- 文创内容和点击内容也已经纳入模板
+
+---
+
+## 1. 顶层默认模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.27",
+  "app": {
+    "id": "sample-event-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,
+    "controlOverrides": {},
+    "metadata": {
+      "title": "默认路线",
+      "code": "default-001"
+    }
+  },
+  "game": {
+    "mode": "classic-sequential",
+    "rulesVersion": "1",
+    "session": {
+      "startManually": true,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": true,
+      "autoFinishOnLastControl": false,
+      "maxDurationSec": 5400
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5,
+      "requiresFocusSelection": false
+    },
+    "sequence": {
+      "skip": {
+        "enabled": false,
+        "radiusMeters": 30,
+        "requiresConfirm": true
+      }
+    },
+    "scoring": {
+      "type": "score",
+      "defaultControlScore": 10
+    },
+    "guidance": {
+      "showLegs": true,
+      "legAnimation": true,
+      "allowFocusSelection": false
+    },
+    "visibility": {
+      "revealFullPlayfieldAfterStartPunch": true
+    },
+    "finish": {
+      "finishControlAlwaysSelectable": false
+    },
+    "telemetry": {
+      "heartRate": {
+        "age": 30,
+        "restingHeartRateBpm": 62,
+        "userWeightKg": 65
+      }
+    },
+    "feedback": {
+      "audioProfile": "default",
+      "hapticsProfile": "default",
+      "uiEffectsProfile": "default"
+    }
+  },
+  "resources": {
+    "audioProfile": "default",
+    "contentProfile": "default",
+    "themeProfile": "default-race"
+  },
+  "debug": {
+    "allowModeSwitch": false,
+    "allowMockInput": false,
+    "allowSimulator": false
+  }
+}
+```
+
+---
+
+## 2. 顺序赛推荐默认模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.27",
+  "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,
+    "controlOverrides": {
+      "start-1": {
+        "title": "比赛开始",
+        "body": "从这里出发，先熟悉地图方向。",
+        "autoPopup": true,
+        "once": true,
+        "priority": 1,
+        "clickTitle": "起点说明",
+        "clickBody": "点击起点可再次查看起跑说明。"
+      },
+      "control-1": {
+        "title": "第一检查点",
+        "body": "完成这个点后沿主路继续前进。",
+        "autoPopup": true,
+        "once": false,
+        "priority": 1,
+        "clickTitle": "第一检查点",
+        "clickBody": "点击查看该点位的补充说明。"
+      },
+      "finish-1": {
+        "title": "比赛结束",
+        "body": "恭喜完成本次路线。",
+        "autoPopup": true,
+        "once": true,
+        "priority": 2,
+        "clickTitle": "终点说明",
+        "clickBody": "点击终点可再次查看结束说明。"
+      }
+    },
+    "metadata": {
+      "title": "顺序赛路线示例",
+      "code": "classic-001"
+    }
+  },
+  "game": {
+    "mode": "classic-sequential",
+    "rulesVersion": "1",
+    "session": {
+      "startManually": true,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": true,
+      "autoFinishOnLastControl": false,
+      "maxDurationSec": 5400
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5,
+      "requiresFocusSelection": false
+    },
+    "sequence": {
+      "skip": {
+        "enabled": false,
+        "radiusMeters": 30,
+        "requiresConfirm": true
+      }
+    },
+    "guidance": {
+      "showLegs": true,
+      "legAnimation": true,
+      "allowFocusSelection": false
+    },
+    "visibility": {
+      "revealFullPlayfieldAfterStartPunch": true
+    },
+    "finish": {
+      "finishControlAlwaysSelectable": false
+    },
+    "telemetry": {
+      "heartRate": {
+        "age": 30,
+        "restingHeartRateBpm": 62,
+        "userWeightKg": 65
+      }
+    },
+    "feedback": {
+      "audioProfile": "default",
+      "hapticsProfile": "default",
+      "uiEffectsProfile": "default"
+    }
+  },
+  "resources": {
+    "audioProfile": "default",
+    "contentProfile": "default",
+    "themeProfile": "default-race"
+  },
+  "debug": {
+    "allowModeSwitch": false,
+    "allowMockInput": false,
+    "allowSimulator": false
+  }
+}
+```
+
+---
+
+## 3. 积分赛推荐默认模板
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.27",
+  "app": {
+    "id": "sample-score-o-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": "control-set",
+    "source": {
+      "type": "kml",
+      "url": "../kml/lxcb-001/10/c01.kml"
+    },
+    "CPRadius": 6,
+    "controlOverrides": {
+      "start-1": {
+        "title": "比赛开始",
+        "body": "从这里触发，先熟悉地图方向。",
+        "autoPopup": true,
+        "once": true,
+        "priority": 1,
+        "clickTitle": "积分赛起点",
+        "clickBody": "点击起点可查看自由打点规则。"
+      },
+      "control-1": {
+        "score": 10,
+        "clickTitle": "1号点",
+        "clickBody": "这是一个基础积分点。"
+      },
+      "control-2": {
+        "score": 20,
+        "autoPopup": false,
+        "once": true,
+        "priority": 1,
+        "clickTitle": "2号点",
+        "clickBody": "这个点配置成点击查看。"
+      },
+      "finish-1": {
+        "title": "比赛结束",
+        "body": "恭喜完成本次路线。",
+        "autoPopup": true,
+        "once": true,
+        "priority": 2,
+        "clickTitle": "终点说明",
+        "clickBody": "点击终点可再次查看结束说明。"
+      }
+    },
+    "metadata": {
+      "title": "积分赛控制点示例",
+      "code": "score-o-001"
+    }
+  },
+  "game": {
+    "mode": "score-o",
+    "rulesVersion": "1",
+    "session": {
+      "startManually": true,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": false,
+      "autoFinishOnLastControl": false,
+      "maxDurationSec": 5400
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 5,
+      "requiresFocusSelection": false
+    },
+    "scoring": {
+      "type": "score",
+      "defaultControlScore": 10
+    },
+    "guidance": {
+      "showLegs": false,
+      "legAnimation": false,
+      "allowFocusSelection": true
+    },
+    "visibility": {
+      "revealFullPlayfieldAfterStartPunch": true
+    },
+    "finish": {
+      "finishControlAlwaysSelectable": true
+    },
+    "telemetry": {
+      "heartRate": {
+        "age": 30,
+        "restingHeartRateBpm": 62,
+        "userWeightKg": 65
+      }
+    },
+    "feedback": {
+      "audioProfile": "default",
+      "hapticsProfile": "default",
+      "uiEffectsProfile": "default"
+    }
+  },
+  "resources": {
+    "audioProfile": "default",
+    "contentProfile": "default",
+    "themeProfile": "default-race"
+  },
+  "debug": {
+    "allowModeSwitch": false,
+    "allowMockInput": false,
+    "allowSimulator": false
+  }
+}
+```
+
+---
+
+## 4. 默认逻辑说明
+
+### 4.1 内容展示默认逻辑
+
+- `title/body`
+  - 未配置时使用系统默认文案
+- `clickTitle/clickBody`
+  - 未配置时回退到 `title/body`
+- `autoPopup`
+  - 默认允许自动弹出
+- `once`
+  - 默认 `false`
+- `priority`
+  - 普通点默认 `1`
+  - 终点默认 `2`
+- 自动打点时：
+  - 自动打点完成后不自动弹内容
+  - 点击内容仍可用
+
+### 4.2 玩法默认逻辑
+
+- 顺序赛默认：
+  - 必须起点
+  - 必须终点
+  - 不自动结束
+  - 跳点默认关闭
+- 积分赛默认：
+  - 必须起点
+  - 终点可选
+  - 不自动结束
+  - 默认分值 `10`
+
+### 4.3 资源默认逻辑
+
+- `audioProfile = default`
+- `contentProfile = default`
+- `themeProfile = default-race`
+
+---
+
+## 5. 建议维护方式
+
+后续每次配置能力扩展时，建议同步维护：
+
+1. [D:\dev\cmr-mini\config-option-dictionary.md](D:/dev/cmr-mini/doc/doc/config-option-dictionary.md)
+2. [D:\dev\cmr-mini\config-default-template.md](D:/dev/cmr-mini/doc/doc/config-default-template.md)
+3. [D:\dev\cmr-mini\event\classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
+4. [D:\dev\cmr-mini\event\score-o.json](D:/dev/cmr-mini/event/score-o.json)
+
+这样可以保证：
+
+- 客户端实现
+- 服务端配置
+- 后台录入
+- 联调样例
+
+始终保持一致。
+