658 lines
12 KiB
Markdown
658 lines
12 KiB
Markdown
# 配置选项字典（当前实现版）
|
||
|
||
本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。
|
||
|
||
目标：
|
||
|
||
- 明确目前哪些字段已经真正生效
|
||
- 明确每个字段的含义、类型、默认逻辑
|
||
- 给后续扩展留下统一维护入口
|
||
|
||
说明：
|
||
|
||
- 本文档优先以“当前代码真实实现”为准
|
||
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
|
||
- 后续每次新增配置能力，都应同步补充本文件
|
||
|
||
---
|
||
|
||
## 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`
|
||
- 说明：打点完成后自动弹出的标题
|
||
|
||
#### `template`
|
||
|
||
- 类型：`string`
|
||
- 说明：原生内容卡模板
|
||
- 当前支持：
|
||
- `minimal`
|
||
- `story`
|
||
- `focus`
|
||
- 建议默认值：
|
||
- 起点/终点：`focus`
|
||
- 普通点：`story`
|
||
|
||
#### `body`
|
||
|
||
- 类型：`string`
|
||
- 说明：打点完成后自动弹出的正文
|
||
|
||
#### `clickTitle`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击控制点时弹出的标题
|
||
- 默认逻辑：未配置时回退到 `title`
|
||
|
||
#### `clickBody`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击控制点时弹出的正文
|
||
- 默认逻辑：未配置时回退到 `body`
|
||
|
||
#### `autoPopup`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：完成该点后是否自动弹出内容
|
||
- 建议默认值：`true`
|
||
- 特殊逻辑：如果当前玩法是自动打点，即 `game.punch.policy = "enter"`，则无论这里如何配置，**都不自动弹出**
|
||
|
||
#### `once`
|
||
|
||
- 类型：`boolean`
|
||
- 说明：该内容是否本局只自动展示一次
|
||
- 建议默认值：`false`
|
||
|
||
#### `priority`
|
||
|
||
- 类型：`number`
|
||
- 说明：内容优先级，越大越高
|
||
- 建议默认值：
|
||
- 普通点：`1`
|
||
- 终点：`2`
|
||
|
||
#### `contentExperience`
|
||
|
||
- 类型：`object`
|
||
- 说明：打点完成后使用的体验承载配置
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：自动弹出内容的承载方式
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `contentExperience.url`
|
||
|
||
- 类型：`string`
|
||
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
|
||
|
||
#### `contentExperience.bridge`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 bridge 版本
|
||
- 建议默认值：`"content-v1"`
|
||
|
||
#### `contentExperience.presentation`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 内容的展示形态
|
||
- 当前支持：
|
||
- `sheet`
|
||
- `dialog`
|
||
- `fullscreen`
|
||
- 建议默认值：`sheet`
|
||
|
||
#### `clickExperience`
|
||
|
||
- 类型：`object`
|
||
- 说明：点击控制点时使用的体验承载配置
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `clickExperience.type`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击内容的承载方式
|
||
- 当前支持：
|
||
- `native`
|
||
- `h5`
|
||
|
||
#### `clickExperience.url`
|
||
|
||
- 类型：`string`
|
||
- 说明：当 `type = "h5"` 时对应的 H5 页面地址
|
||
|
||
#### `clickExperience.bridge`
|
||
|
||
- 类型：`string`
|
||
- 说明：H5 bridge 版本
|
||
- 建议默认值：`"content-v1"`
|
||
|
||
#### `clickExperience.presentation`
|
||
|
||
- 类型：`string`
|
||
- 说明：点击内容的展示形态
|
||
- 当前支持：
|
||
- `sheet`
|
||
- `dialog`
|
||
- `fullscreen`
|
||
- 建议默认值：`sheet`
|
||
|
||
### 6.3 示例
|
||
|
||
```json
|
||
"controlOverrides": {
|
||
"start-1": {
|
||
"template": "focus",
|
||
"title": "比赛开始",
|
||
"body": "从这里出发，先熟悉地图方向。",
|
||
"autoPopup": true,
|
||
"once": true,
|
||
"priority": 1,
|
||
"clickTitle": "起点说明",
|
||
"clickBody": "点击起点可再次查看起跑说明。"
|
||
},
|
||
"control-2": {
|
||
"template": "minimal",
|
||
"score": 20,
|
||
"title": "教学楼南侧",
|
||
"body": "这里是重要转折点。",
|
||
"autoPopup": false,
|
||
"once": true,
|
||
"priority": 1,
|
||
"clickTitle": "教学楼南侧",
|
||
"clickBody": "这个点配置成点击查看。",
|
||
"contentExperience": {
|
||
"type": "h5",
|
||
"url": "https://example.com/content/control-2",
|
||
"bridge": "content-v1",
|
||
"presentation": "sheet"
|
||
},
|
||
"clickExperience": {
|
||
"type": "h5",
|
||
"url": "https://example.com/content/control-2-click",
|
||
"bridge": "content-v1",
|
||
"presentation": "dialog"
|
||
}
|
||
},
|
||
"finish-1": {
|
||
"template": "focus",
|
||
"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` 目录下的配置样例
|
||
|
||
这样可以保证：
|
||
|
||
- 服务端可对照
|
||
- 后台可录入
|
||
- 客户端联调时有统一参考
|