# 配置选项字典（当前实现版）

本文档用于整理 **当前客户端已经消费或已经预留承载的配置项**，作为事件配置、后台配置和联调时的统一参考。

目标：

- 明确目前哪些字段已经真正生效
- 明确每个字段的含义、类型、默认逻辑
- 给后续扩展留下统一维护入口

说明：

- 本文档优先以“当前代码真实实现”为准
- 未列出的字段，不代表未来不能加，只代表当前客户端未正式消费
- 后续每次新增配置能力，都应同步补充本文件

---

## 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`
- 说明：点击内容的展示形态

#### `pointStyle`

- 类型：`string`
- 说明：单个控制点的样式覆盖，仅影响当前控制点
- 支持值：
  - `classic-ring`
  - `solid-dot`
  - `double-ring`
  - `badge`
  - `pulse-core`

#### `pointColorHex`

- 类型：`string`
- 说明：单个控制点的颜色覆盖，例如 `#27ae60`
- 备注：通常和 `pointStyle` 一起使用，未配置时回退到玩法样式 profile

#### `pointSizeScale`

- 类型：`number`
- 说明：单个控制点的尺寸倍率覆盖
- 建议范围：`0.6 ~ 1.4`
- 建议默认值：`1`
- 备注：大于 `1` 会放大点位，小于 `1` 会缩小点位

#### `pointAccentRingScale`

- 类型：`number`
- 说明：单个控制点强调环/外环的尺寸倍率
- 建议范围：`1.0 ~ 1.6`
- 建议默认值：由样式 profile 决定
- 备注：适合当前点、高分点、终点这类需要更强层次感的点位

#### `pointGlowStrength`

- 类型：`number`
- 说明：单个控制点的光晕强度
- 建议范围：`0 ~ 1`
- 建议默认值：`0`
- 备注：`0` 为无光晕，越接近 `1` 光晕越明显

#### `pointLabelScale`

- 类型：`number`
- 说明：单个控制点编号文字的尺寸倍率
- 建议范围：`0.7 ~ 1.3`
- 建议默认值：`1`
- 备注：适合高价值点、终点、特殊活动点的编号强调

#### `pointLabelColorHex`

- 类型：`string`
- 说明：单个控制点编号文字颜色覆盖，例如 `#ffffff`
- 备注：未配置时回退到样式系统默认标签颜色逻辑
- 当前支持：
  - `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. `game.presentation`

### `game.presentation.sequential.controls.default`

- 类型：`object`
- 说明：顺序赛普通未完成控制点的默认样式
- 支持字段：
  - `style`：`classic-ring | solid-dot | double-ring | badge | pulse-core`
  - `colorHex`：十六进制颜色，例如 `#cc006b`
  - `sizeScale`：点位尺寸倍率
  - `accentRingScale`：强调环尺寸倍率
  - `glowStrength`：点位光晕强度
  - `labelScale`：编号文字尺寸倍率
  - `labelColorHex`：编号文字颜色

### `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`
- 说明：顺序赛终点样式

### `game.presentation.sequential.legs.default`

- 类型：`object`
- 说明：顺序赛默认路线腿样式
- 支持字段：
  - `style`：`classic-leg | dashed-leg | glow-leg | progress-leg`
  - `colorHex`：十六进制颜色
  - `widthScale`：路线腿宽度倍率
  - `glowStrength`：路线腿光晕强度

### `game.presentation.sequential.legs.completed`

- 类型：`object`
- 说明：顺序赛已完成路线腿样式

### `playfield.legOverrides`

- 类型：`object`
- 说明：对指定路线腿做局部样式覆盖
- 键名建议：
  - `leg-1`
  - `leg-2`
  - `leg-3`

- 字段：
  - `style`：`classic-leg | dashed-leg | glow-leg | progress-leg`
  - `colorHex`：十六进制颜色
  - `widthScale`：路线腿宽度倍率
  - `glowStrength`：路线腿光晕强度

- 示例：

```json
"legOverrides": {
  "leg-2": {
    "style": "glow-leg",
    "colorHex": "#27ae60"
  }
}
```

### `game.presentation.scoreO.controls.default`

- 类型：`object`
- 说明：积分赛默认点位样式

### `game.presentation.scoreO.controls.focused`

- 类型：`object`
- 说明：积分赛当前聚焦/选中点样式

### `game.presentation.scoreO.controls.collected`

- 类型：`object`
- 说明：积分赛已收集点样式

### `game.presentation.scoreO.controls.start`

- 类型：`object`
- 说明：积分赛起点样式

### `game.presentation.scoreO.controls.finish`

- 类型：`object`
- 说明：积分赛终点样式

### `game.presentation.scoreO.controls.scoreBands`

- 类型：`array`
- 说明：积分赛按分值档位映射点位颜色和样式
- 数组项字段：
  - `min`：分值下界，含
  - `max`：分值上界，含
  - `style`：`classic-ring | solid-dot | double-ring | badge | pulse-core`
  - `colorHex`：十六进制颜色
  - `sizeScale`：该积分档位的点位尺寸倍率
  - `accentRingScale`：该积分档位的强调环倍率
  - `glowStrength`：该积分档位的光晕强度
  - `labelScale`：该积分档位的编号文字尺寸倍率
  - `labelColorHex`：该积分档位的编号文字颜色

- 示例：

```json
"presentation": {
  "scoreO": {
    "controls": {
      "scoreBands": [
        { "min": 0, "max": 19, "style": "classic-ring", "colorHex": "#56ccf2" },
        { "min": 20, "max": 49, "style": "double-ring", "colorHex": "#f2c94c" },
        { "min": 50, "max": 999999, "style": "badge", "colorHex": "#eb5757" }
      ]
    }
  }
}
```

---

## 20. `game.presentation.track`

- 类型：`object`
- 说明：用户轨迹显示策略与样式配置

### `game.presentation.track.mode`

- 类型：`string`
- 说明：轨迹显示模式
- 当前支持：
  - `none`：不显示轨迹
  - `tail`：彗尾拖尾
  - `full`：全轨迹
- 建议默认值：
  - 顺序赛：`full`
  - 积分赛：`tail`

### `game.presentation.track.style`

- 类型：`string`
- 说明：轨迹风格 profile
- 当前支持：
  - `classic`
  - `neon`
- 当前默认值：`neon`

### `game.presentation.track.tailLength`

- 类型：`string`
- 说明：拖尾基础长度档位
- 当前支持：
  - `short`
  - `medium`
  - `long`
- 备注：
  - 实际显示长度会继续按移动速度动态变化
  - 跑得越快，尾巴越长
  - 跑得越慢，尾巴越短

### `game.presentation.track.colorPreset`

- 类型：`string`
- 说明：轨迹亮色调色盘
- 当前支持：
  - `mint`
  - `cyan`
  - `sky`
  - `blue`
  - `violet`
  - `pink`
  - `orange`
  - `yellow`
- 备注：
  - 运行时会在此基础上根据速度和心率张力自动提亮头部颜色与光晕

### `game.presentation.track.tailMeters`

- 类型：`number`
- 说明：拖尾基础长度（米）
- 备注：
  - 若未显式配置，则按 `tailLength` 自动映射

### `game.presentation.track.tailMaxSeconds`

- 类型：`number`
- 说明：拖尾最大时间窗口（秒）

### `game.presentation.track.fadeOutWhenStill`

- 类型：`boolean`
- 说明：静止后是否逐步收尾消失

### `game.presentation.track.stillSpeedKmh`

- 类型：`number`
- 说明：低于该速度时进入静止收尾逻辑

### `game.presentation.track.fadeOutDurationMs`

- 类型：`number`
- 说明：静止后拖尾完全淡出的时长（毫秒）

### `game.presentation.track.colorHex`

- 类型：`string`
- 说明：轨迹主色
- 备注：
  - 未配置时按 `colorPreset` 自动映射

### `game.presentation.track.headColorHex`

- 类型：`string`
- 说明：轨迹头部高亮颜色
- 备注：
  - 未配置时按 `colorPreset` 自动映射

### `game.presentation.track.widthPx`

- 类型：`number`
- 说明：轨迹基础宽度

### `game.presentation.track.headWidthPx`

- 类型：`number`
- 说明：轨迹头部高亮宽度

### `game.presentation.track.glowStrength`

- 类型：`number`
- 说明：轨迹光晕强度
- 备注：
  - `standard / lite` 会自动做 glow 强度降级

---

## 21. `game.presentation.gpsMarker`

- 类型：`object`
- 说明：GPS 定位点显示、尺寸、颜色、朝向指示和品牌化扩展配置

### `game.presentation.gpsMarker.visible`

- 类型：`boolean`
- 说明：是否显示 GPS 定位点
- 当前默认值：`true`

### `game.presentation.gpsMarker.style`

- 类型：`string`
- 说明：GPS 点基础样式
- 当前支持：
  - `dot`
  - `beacon`
  - `disc`
  - `badge`
- 当前默认值：`beacon`

### `game.presentation.gpsMarker.size`

- 类型：`string`
- 说明：GPS 点整体大小档位
- 当前支持：
  - `small`
  - `medium`
  - `large`
- 当前默认值：`medium`

### `game.presentation.gpsMarker.colorPreset`

- 类型：`string`
- 说明：GPS 点亮色调色盘
- 当前支持：
  - `mint`
  - `cyan`
  - `sky`
  - `blue`
  - `violet`
  - `pink`
  - `orange`
  - `yellow`
- 当前默认值：`cyan`

### `game.presentation.gpsMarker.colorHex`

- 类型：`string`
- 说明：GPS 点主色
- 备注：
  - 未配置时按 `colorPreset` 自动映射

### `game.presentation.gpsMarker.ringColorHex`

- 类型：`string`
- 说明：GPS 点外圈颜色
- 备注：
  - 未配置时按 `colorPreset` 自动映射

### `game.presentation.gpsMarker.indicatorColorHex`

- 类型：`string`
- 说明：朝向小三角颜色
- 备注：
  - 未配置时按 `colorPreset` 自动映射

### `game.presentation.gpsMarker.showHeadingIndicator`

- 类型：`boolean`
- 说明：是否显示跟随朝向旋转的小三角
- 当前默认值：`true`
- 备注：
  - 运行时会结合朝向可信度自动降低透明度

### `game.presentation.gpsMarker.animationProfile`

- 类型：`string`
- 说明：GPS 点动画 profile
- 当前支持：
  - `minimal`
  - `dynamic-runner`
  - `warning-reactive`
- 当前默认值：`dynamic-runner`
- 备注：
  - 第一阶段主要影响静止、移动、高速和高压状态下的动势强弱
  - 未配置时使用系统默认动画逻辑

### `game.presentation.gpsMarker.logoUrl`

- 类型：`string`
- 说明：品牌 logo 资源地址
- 当前状态：已支持中心贴片
- 备注：
  - logo 作为中心贴片嵌入 GPS 点，不直接替代定位点
  - 建议使用透明背景正方形资源

### `game.presentation.gpsMarker.logoMode`

- 类型：`string`
- 说明：logo 嵌入方式
- 当前支持：
  - `center-badge`
- 当前状态：已支持

---

## 22. 当前默认逻辑说明

当前客户端对配置的处理原则是：

- 能有默认值的尽量给默认值
- 控制点内容类字段缺失时走默认文案
- `clickTitle/clickBody` 缺失时回退到 `title/body`
- 自动打点模式下不自动弹内容
- 内容优先级未配置时使用普通点 `1`、终点 `2`

也就是说：

**大部分配置项都不是强制必填，先保证主骨架完整即可。**

---

## 23. 维护约定

后续每次新增配置项时，应同步更新：

1. 本文档
2. 默认模板文档
3. `event` 目录下的配置样例

这样可以保证：

- 服务端可对照
- 后台可录入
- 客户端联调时有统一参考