zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
zhangyan
2026-03-27 15:36:27 +08:00
parent 0e025c3426
commit 0e0a724025
55 changed files with 4177 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

556
doc/config-option-dictionary.md Normal file
View File

@@ -0,0 +1,556 @@
# 配置选项字典（当前实现版）
本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。
目标：
- 明确目前哪些字段已经真正生效
- 明确每个字段的含义、类型、默认逻辑
- 给后续扩展留下统一维护入口
说明：
- 本文档优先以“当前代码真实实现”为准
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
- 后续每次新增配置能力，都应同步补充本文件
---
## 1. 顶层结构
当前推荐结构：
```json
{
"schemaVersion": "1",
"version": "2026.03.27",
"app": {},
"map": {},
"playfield": {},
"game": {},
"resources": {},
"debug": {}
}
```
---
## 2. 顶层字段字典
### `schemaVersion`
- 类型：`string`
- 说明：配置结构版本
- 建议默认值：`"1"`
### `version`
- 类型：`string`
- 说明：当前配置内容版本
- 建议默认值：日期或发布版本号，例如 `2026.03.27`
### `app`
- 类型：`object`
- 说明：活动级基础信息
### `map`
- 类型：`object`
- 说明：地图底座信息
### `playfield`
- 类型：`object`
- 说明：玩法空间对象与内容覆盖
### `game`
- 类型：`object`
- 说明：玩法规则与局流程
### `resources`
- 类型：`object`
- 说明：资源 profile 引用
### `debug`
- 类型：`object`
- 说明：调试开关
---
## 3. `app` 字段
### `app.id`
- 类型：`string`
- 说明：活动或配置实例 id
- 示例：`"sample-classic-001"`
### `app.title`
- 类型：`string`
- 说明：活动标题 / 比赛名称
- 示例：`"顺序赛示例"`
### `app.locale`
- 类型：`string`
- 说明：语言环境
- 建议默认值：`"zh-CN"`
---
## 4. `map` 字段
### `map.tiles`
- 类型：`string`
- 说明：瓦片根路径
- 必填：是
### `map.mapmeta`
- 类型：`string`
- 说明：地图 meta 文件地址
- 必填：是
### `map.declination`
- 类型：`number`
- 说明：磁偏角
- 示例：`6.91`
- 备注：当前会影响真北/磁北换算
### `map.initialView.zoom`
- 类型：`number`
- 说明：初始缩放级别
- 建议默认值：`17`
---
## 5. `playfield` 字段
### `playfield.kind`
- 类型：`string`
- 说明：空间对象类型
- 当前推荐值：
- `course`
- `control-set`
### `playfield.source.type`
- 类型：`string`
- 说明：空间底稿来源类型
- 当前推荐值：`kml`
### `playfield.source.url`
- 类型：`string`
- 说明：KML 地址
- 必填：是
### `playfield.CPRadius`
- 类型：`number`
- 说明：检查点绘制半径
- 建议默认值：`6`
### `playfield.metadata.title`
- 类型：`string`
- 说明：路线或控制点集标题
### `playfield.metadata.code`
- 类型：`string`
- 说明：路线或控制点集编码
---
## 6. `playfield.controlOverrides`
`playfield.controlOverrides` 用于对起点、检查点、终点做内容或分值覆盖。
### 6.1 key 命名规则
- 起点：`start-1`
- 普通检查点：`control-1`、`control-2`、`control-3`
- 终点：`finish-1`
### 6.2 当前支持字段
#### `score`
- 类型：`number`
- 说明：积分赛控制点分值
- 适用：积分赛
#### `title`
- 类型：`string`
- 说明：打点完成后自动弹出的标题
#### `body`
- 类型：`string`
- 说明：打点完成后自动弹出的正文
#### `clickTitle`
- 类型：`string`
- 说明：点击控制点时弹出的标题
- 默认逻辑：未配置时回退到 `title`
#### `clickBody`
- 类型：`string`
- 说明：点击控制点时弹出的正文
- 默认逻辑：未配置时回退到 `body`
#### `autoPopup`
- 类型：`boolean`
- 说明：完成该点后是否自动弹出内容
- 建议默认值：`true`
- 特殊逻辑：如果当前玩法是自动打点，即 `game.punch.policy = "enter"`，则无论这里如何配置，**都不自动弹出**
#### `once`
- 类型：`boolean`
- 说明：该内容是否本局只自动展示一次
- 建议默认值：`false`
#### `priority`
- 类型：`number`
- 说明：内容优先级，越大越高
- 建议默认值：
- 普通点：`1`
- 终点：`2`
### 6.3 示例
```json
"controlOverrides": {
"start-1": {
"title": "比赛开始",
"body": "从这里出发，先熟悉地图方向。",
"autoPopup": true,
"once": true,
"priority": 1,
"clickTitle": "起点说明",
"clickBody": "点击起点可再次查看起跑说明。"
},
"control-2": {
"score": 20,
"title": "教学楼南侧",
"body": "这里是重要转折点。",
"autoPopup": false,
"once": true,
"priority": 1,
"clickTitle": "教学楼南侧",
"clickBody": "这个点配置成点击查看。"
},
"finish-1": {
"title": "比赛结束",
"body": "恭喜完成本次路线。",
"autoPopup": true,
"once": true,
"priority": 2,
"clickTitle": "终点说明",
"clickBody": "点击终点可再次查看结束说明。"
}
}
```
---
## 7. `game` 字段
### `game.mode`
- 类型：`string`
- 说明：玩法类型
- 当前支持：
- `classic-sequential`
- `score-o`
### `game.rulesVersion`
- 类型：`string`
- 说明：规则版本
- 建议默认值：`"1"`
---
## 8. `game.session`
### `game.session.startManually`
- 类型：`boolean`
- 说明：是否需要手动点击开始
- 建议默认值：`true`
### `game.session.requiresStartPunch`
- 类型：`boolean`
- 说明：是否必须完成起点打卡
- 建议默认值：
- 顺序赛：`true`
- 积分赛：`true`
### `game.session.requiresFinishPunch`
- 类型：`boolean`
- 说明：是否必须完成终点打卡
- 建议默认值：
- 顺序赛：`true`
- 积分赛：`false`
### `game.session.autoFinishOnLastControl`
- 类型：`boolean`
- 说明：是否打完最后控制点自动结束
- 建议默认值：`false`
### `game.session.maxDurationSec`
- 类型：`number`
- 说明：最大比赛时长，单位秒
- 建议默认值：`5400`
---
## 9. `game.punch`
### `game.punch.policy`
- 类型：`string`
- 说明：打点策略
- 当前支持：
- `enter-confirm`
- `enter`
- 建议默认值：`enter-confirm`
### `game.punch.radiusMeters`
- 类型：`number`
- 说明：打点半径
- 建议默认值：`5`
### `game.punch.requiresFocusSelection`
- 类型：`boolean`
- 说明：积分赛是否需要先选中目标再打卡
- 建议默认值：
- 顺序赛：`false`
- 积分赛：`false`
---
## 10. `game.sequence.skip`
仅顺序赛相关。
### `game.sequence.skip.enabled`
- 类型：`boolean`
- 说明：是否允许跳点
- 建议默认值：`false`
### `game.sequence.skip.radiusMeters`
- 类型：`number`
- 说明：跳点半径
- 建议默认值：`30`
### `game.sequence.skip.requiresConfirm`
- 类型：`boolean`
- 说明：跳点是否需要确认
- 建议默认值：`true`
---
## 11. `game.scoring`
### `game.scoring.type`
- 类型：`string`
- 说明：积分模型
- 当前推荐值：`score`
### `game.scoring.defaultControlScore`
- 类型：`number`
- 说明：积分赛默认控制点分值
- 建议默认值：`10`
---
## 12. `game.guidance`
### `game.guidance.showLegs`
- 类型：`boolean`
- 说明：是否显示腿线
- 建议默认值：
- 顺序赛：`true`
- 积分赛：`false`
### `game.guidance.legAnimation`
- 类型：`boolean`
- 说明：是否显示腿线动画
- 建议默认值：
- 顺序赛：`true`
- 积分赛：`false`
### `game.guidance.allowFocusSelection`
- 类型：`boolean`
- 说明：是否允许地图点击选择目标点
- 建议默认值：
- 顺序赛：`false`
- 积分赛：`true`
---
## 13. `game.visibility`
### `game.visibility.revealFullPlayfieldAfterStartPunch`
- 类型：`boolean`
- 说明：起点打卡后是否显示完整路线/控制点集合
- 建议默认值：`true`
---
## 14. `game.finish`
### `game.finish.finishControlAlwaysSelectable`
- 类型：`boolean`
- 说明：终点是否始终可选
- 建议默认值：
- 顺序赛：`false`
- 积分赛：`true`
---
## 15. `game.telemetry.heartRate`
### `age`
- 类型：`number`
- 说明：年龄
- 建议默认值：`30`
### `restingHeartRateBpm`
- 类型：`number`
- 说明：静息心率
- 建议默认值：`62`
### `userWeightKg`
- 类型：`number`
- 说明：体重
- 建议默认值：`65`
---
## 16. `game.feedback`
### `game.feedback.audioProfile`
- 类型：`string`
- 说明：音频反馈 profile
- 建议默认值：`default`
### `game.feedback.hapticsProfile`
- 类型：`string`
- 说明：震动反馈 profile
- 建议默认值：`default`
### `game.feedback.uiEffectsProfile`
- 类型：`string`
- 说明：UI 动效 profile
- 建议默认值：`default`
---
## 17. `resources`
### `resources.audioProfile`
- 类型：`string`
- 建议默认值：`default`
### `resources.contentProfile`
- 类型：`string`
- 建议默认值：`default`
### `resources.themeProfile`
- 类型：`string`
- 建议默认值：`default-race`
---
## 18. `debug`
### `debug.allowModeSwitch`
- 类型：`boolean`
- 建议默认值：`false`
### `debug.allowMockInput`
- 类型：`boolean`
- 建议默认值：`false`
### `debug.allowSimulator`
- 类型：`boolean`
- 建议默认值：`false`
---
## 19. 当前默认逻辑说明
当前客户端对配置的处理原则是：
- 能有默认值的尽量给默认值
- 控制点内容类字段缺失时走默认文案
- `clickTitle/clickBody` 缺失时回退到 `title/body`
- 自动打点模式下不自动弹内容
- 内容优先级未配置时使用普通点 `1`、终点 `2`
也就是说：
**大部分配置项都不是强制必填，先保证主骨架完整即可。**
---
## 20. 维护约定
后续每次新增配置项时，应同步更新：
1. 本文档
2. 默认模板文档
3. `event` 目录下的配置样例
这样可以保证：
- 服务端可对照
- 后台可录入
- 客户端联调时有统一参考