整理文档并接入 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-template-classic-sequential.md
+++ b/doc/config-template-classic-sequential.md
@@ -0,0 +1,313 @@
+# 顺序赛配置文档（基础版）
+
+本文档用于给服务端和后台配置设计提供一份可直接落地的顺序赛基础模板。  
+目标是先把入口配置结构定稳，后续程序功能再逐步细化。
+
+---
+
+## 1. 适用玩法
+
+适用于最基础的顺序打点玩法：
+
+- 手动开始
+- 先打开始点
+- 按顺序打检查点
+- 最后打终点
+- 支持正常打点半径
+- 预留后续扩展规则空间
+
+---
+
+## 2. 顶层结构
+
+推荐主配置结构如下：
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.25",
+  "app": {},
+  "map": {},
+  "playfield": {},
+  "game": {},
+  "resources": {},
+  "debug": {}
+}
+```
+
+---
+
+## 3. 完整示例
+
+```json
+{
+  "schemaVersion": "1",
+  "version": "2026.03.25",
+  "app": {
+    "id": "lxcb-001",
+    "title": "雪熊领秀城区顺序赛",
+    "locale": "zh-CN"
+  },
+  "map": {
+    "tiles": "lxcb-001/tiles/",
+    "mapmeta": "lxcb-001/tiles/meta.json",
+    "declination": 6.91,
+    "initialView": {
+      "zoom": 17
+    }
+  },
+  "playfield": {
+    "kind": "course",
+    "source": {
+      "type": "kml",
+      "url": "lxcb-001/course/c01.kml"
+    },
+    "CPRadius": 6,
+    "metadata": {
+      "title": "校园经典路线",
+      "code": "c01"
+    }
+  },
+  "game": {
+    "mode": "classic-sequential",
+    "rulesVersion": "1",
+    "session": {
+      "startManually": true,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": true,
+      "autoFinishOnLastControl": false,
+      "maxDurationSec": 5400
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 10
+    },
+    "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
+  }
+}
+```
+
+---
+
+## 4. 字段说明
+
+### `app`
+
+- `id`
+  活动或配置实例 id
+- `title`
+  活动标题
+- `locale`
+  语言环境
+
+### `map`
+
+- `tiles`
+  瓦片根路径
+- `mapmeta`
+  地图 meta 地址
+- `declination`
+  磁偏角
+- `initialView.zoom`
+  初始缩放级别
+
+### `playfield`
+
+- `kind`
+  当前为 `course`
+- `source.type`
+  当前推荐为 `kml`
+- `source.url`
+  KML 地址
+- `CPRadius`
+  检查点绘制半径，单位米
+- `metadata`
+  路线元数据
+
+### `game.session`
+
+- `startManually`
+  是否需要先点击开始按钮
+- `requiresStartPunch`
+  是否必须先打开始点
+- `requiresFinishPunch`
+  是否必须打终点
+- `autoFinishOnLastControl`
+  是否打完最后一个检查点自动结束
+- `maxDurationSec`
+  最大比赛时长
+
+### `game.punch`
+
+- `policy`
+  当前推荐 `enter-confirm`
+- `radiusMeters`
+  正常打点半径
+
+### `game.sequence`
+
+- `skip`
+  顺序赛跳点规则
+- `enabled`
+  是否允许跳点
+- `radiusMeters`
+  跳点半径，必须大于打点半径
+- `requiresConfirm`
+  是否必须用户确认后跳点
+
+当前基础版建议先关闭：
+
+```json
+"enabled": false
+```
+
+### `game.guidance`
+
+- `showLegs`
+  是否显示腿线
+- `legAnimation`
+  是否显示当前腿动画
+- `allowFocusSelection`
+  顺序赛一般为 `false`
+
+### `game.visibility`
+
+- `revealFullPlayfieldAfterStartPunch`
+  开始点打卡后是否显示完整路线
+
+### `game.finish`
+
+- `finishControlAlwaysSelectable`
+  顺序赛一般为 `false`
+
+### `game.telemetry`
+
+通用体能参数。
+
+### `game.feedback`
+
+反馈 profile 绑定。
+
+### `resources`
+
+资源 profile 绑定。
+
+### `debug`
+
+调试相关开关。
+
+---
+
+## 5. 当前阶段推荐必填字段
+
+顺序赛当前阶段建议至少保证以下字段存在：
+
+- `map.tiles`
+- `map.mapmeta`
+- `map.declination`
+- `playfield.kind`
+- `playfield.source.type`
+- `playfield.source.url`
+- `playfield.CPRadius`
+- `game.mode`
+- `game.punch.policy`
+- `game.punch.radiusMeters`
+- `game.session.requiresStartPunch`
+- `game.session.requiresFinishPunch`
+
+---
+
+## 6. 当前阶段建议默认值
+
+如果服务端还没有全部配置细项，建议先采用以下默认值：
+
+```json
+{
+  "game": {
+    "session": {
+      "startManually": true,
+      "requiresStartPunch": true,
+      "requiresFinishPunch": true,
+      "autoFinishOnLastControl": false
+    },
+    "punch": {
+      "policy": "enter-confirm",
+      "radiusMeters": 10
+    },
+    "sequence": {
+      "skip": {
+        "enabled": false,
+        "radiusMeters": 30,
+        "requiresConfirm": true
+      }
+    },
+    "guidance": {
+      "showLegs": true,
+      "legAnimation": true,
+      "allowFocusSelection": false
+    }
+  }
+}
+```
+
+---
+
+## 7. 适合当前客户端的迁移原则
+
+当前客户端迁移时，建议服务端先完成：
+
+1. 将老字段逐步迁入 `map / playfield / game / resources / debug`
+2. 保持基础字段完整
+3. 不急着一次性把所有高级规则上线
+
+优先把“入口结构”夯实，再逐步扩玩法参数。
+
+---
+
+## 8. 一句话结论
+
+顺序赛配置当前阶段建议：
+
+- 用 `playfield.kind = course`
+- 用 KML 承载空间底稿
+- 用 `game.session / game.punch / game.sequence / game.guidance` 承载玩法规则
+- 先把基础入口结构定稳，后续再细化跳点、惩罚、特殊引导等高级规则