# 配置分级总表
> 文档版本：v1.0
> 最后更新：2026-04-02


本文档用于把当前配置体系按“核心必需项 / 常用活动项 / 高级实验项”三层整理，作为后续后台配置设计、活动装配和字段治理的统一依据。

目标：

- 防止把所有内部变量都直接暴露成后台配置
- 明确哪些字段适合最先做成后台表单
- 明确哪些字段只应保留在高级配置区或 JSON 扩展区
- 支撑“默认能跑、少配能跑、多配能扩”的可伸缩配置方案

说明：

- 本文档关注的是“字段开放策略”，不是字段字典本身
- 字段定义、类型、默认值仍以 [配置选项字典](D:/dev/cmr-mini/doc/config/配置选项字典.md) 为准
- 玩法专属使用范围仍以各玩法目录下的文档为准

---

## 1. 分级原则

### 1.1 核心必需项

满足以下条件的字段应归入核心必需项：

- 不填就无法正常进入游戏
- 不填会导致地图、场地或玩法主流程无法成立
- 后台创建一个新活动时几乎一定会填写

特点：

- 数量要少
- 后台首屏就能录入
- 应优先做成明确表单项

### 1.2 常用活动项

满足以下条件的字段应归入常用活动项：

- 不填也能跑，但活动运营经常会改
- 改动后会明显影响玩家体验或活动策略
- 属于“常见活动差异”，而不是内部实现细节

特点：

- 可以在后台做成“高级设置”分组
- 建议有默认值
- 应控制数量，避免首版后台过重

### 1.3 高级实验项

满足以下条件的字段应归入高级实验项：

- 只在少数玩法或实验活动中才需要
- 更偏表现调优、体验实验、联调或研发控制
- 暂时不适合做成常规后台表单

特点：

- 默认不暴露给普通运营
- 更适合放在高级 JSON 区或内部配置区
- 后续可以按实际使用频率再降级到常用活动项

---

## 2. 推荐后台策略

建议后续后台按三层展示：

1. 基础信息
2. 常用活动设置
3. 高级配置

其中：

- 基础信息只对应核心必需项
- 常用活动设置对应常用活动项
- 高级配置对应高级实验项和 JSON 扩展

不建议：

- 首版后台直接开放全部字段
- 把玩家个人设置和活动规则配置混在一起
- 把纯运行时状态做成配置项

---

## 3. 当前分级总表

### 3.1 核心必需项

| 字段 | 说明 | 备注 |
| --- | --- | --- |
| `schemaVersion` | 配置结构版本 | 建议固定为 `"1"` |
| `version` | 配置版本号 | 建议按发布日期或发布号维护 |
| `app.id` | 活动实例 ID | 必填 |
| `app.title` | 活动标题 | 必填 |
| `map.tiles` | 瓦片根路径 | 必填 |
| `map.mapmeta` | 地图元数据路径 | 必填 |
| `playfield.kind` | 场地类型 | 顺序赛常用 `course`，积分赛常用 `control-set` |
| `playfield.source.type` | 场地来源类型 | 当前推荐 `kml` |
| `playfield.source.url` | 场地源文件路径 | 必填 |
| `game.mode` | 玩法模式 | 当前核心玩法：`classic-sequential` / `score-o` |

建议：

- 核心必需项应控制在 `10` 个左右
- 新活动创建时，后台优先只要求填写这一层

### 3.2 常用活动项

| 字段 | 说明 | 备注 |
| --- | --- | --- |
| `app.locale` | 语言环境 | 常见默认值 `zh-CN` |
| `settings.*.value` | 系统设置默认值 | 活动可覆盖玩家默认体验 |
| `settings.*.isLocked` | 系统设置锁态 | 只在本局生命周期内生效 |
| `map.declination` | 磁偏角 | 地图类活动常用 |
| `map.initialView.zoom` | 初始缩放 | 常见活动会调 |
| `playfield.CPRadius` | 控制点绘制半径 | 常用地图表现项 |
| `playfield.metadata.title` | 路线标题 | 常用展示信息 |
| `playfield.metadata.code` | 路线编码 | 常用管理字段 |
| `playfield.controlOverrides.<key>.score` | 点位分值覆盖 | 积分赛常用 |
| `game.session.requiresStartPunch` | 是否要求起点打卡 | 常用局流程控制 |
| `game.session.requiresFinishPunch` | 是否要求终点打卡 | 常用局流程控制 |
| `game.session.autoFinishOnLastControl` | 最后点自动结束 | 常用局流程控制 |
| `game.session.maxDurationSec` | 最大时长 / 关门时间 | 常用赛事规则项 |
| `game.punch.policy` | 打点方式 | 常用玩法差异项 |
| `game.punch.radiusMeters` | 打点半径 | 常用活动调节项 |
| `game.punch.requiresFocusSelection` | 是否先选目标 | 积分赛常用 |
| `game.sequence.skip.enabled` | 是否允许跳点 | 顺序赛常用 |
| `game.sequence.skip.radiusMeters` | 跳点半径 | 顺序赛常用 |
| `game.sequence.skip.requiresConfirm` | 跳点是否确认 | 顺序赛常用 |
| `game.guidance.showLegs` | 是否显示腿线 | 常用表现项 |
| `game.guidance.legAnimation` | 腿线动画 | 常用表现项 |
| `game.guidance.allowFocusSelection` | 是否允许地图选点 | 积分赛常用 |
| `game.visibility.revealFullPlayfieldAfterStartPunch` | 起点后是否揭示全场 | 常用局流程表现项 |
| `game.finish.finishControlAlwaysSelectable` | 终点是否始终可打 | 积分赛常用 |
| `game.scoring.defaultControlScore` | 默认点位分值 | 常用计分项 |

建议：

- 常用活动项是后台第二层的重点
- 这层优先服务“活动策划/运营经常会改的东西”

### 3.3 高级实验项

| 字段 | 说明 | 备注 |
| --- | --- | --- |
| `playfield.controlOverrides.<key>.template` | 白卡模板 | 内容实验项 |
| `playfield.controlOverrides.<key>.title` | 打点后内容标题 | 内容实验项 |
| `playfield.controlOverrides.<key>.body` | 打点后内容正文 | 内容实验项 |
| `playfield.controlOverrides.<key>.clickTitle` | 点击内容标题 | 显式启用型能力 |
| `playfield.controlOverrides.<key>.clickBody` | 点击内容正文 | 显式启用型能力 |
| `playfield.controlOverrides.<key>.autoPopup` | 是否自动弹白卡 | 内容实验项 |
| `playfield.controlOverrides.<key>.once` | 是否仅一次 | 内容实验项 |
| `playfield.controlOverrides.<key>.priority` | 内容优先级 | 内容实验项 |
| `playfield.controlOverrides.<key>.contentExperience.*` | 打点后 H5 / 原生体验 | 高级体验项 |
| `playfield.controlOverrides.<key>.clickExperience.*` | 点击 H5 / 原生体验 | 高级体验项 |
| `playfield.controlOverrides.<key>.pointStyle` | 单点样式覆盖 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointColorHex` | 单点颜色覆盖 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointSizeScale` | 单点尺寸倍率 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointAccentRingScale` | 单点强调环倍率 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointGlowStrength` | 单点光晕强度 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointLabelScale` | 标签缩放 | 表现调优项 |
| `playfield.controlOverrides.<key>.pointLabelColorHex` | 标签颜色覆盖 | 表现调优项 |
| `playfield.legOverrides.<key>.*` | 腿线局部覆盖 | 表现调优项 |
| `game.presentation.*` | 全局点位/腿线样式 | 当前更适合高级区 |
| `game.presentation.track.*` | 轨迹表现细项 | 高级表现区 |
| `game.presentation.gpsMarker.*` | GPS 点表现细项 | 高级表现区 |
| `game.telemetry.*` | 遥测计算参数 | 高级区或设备联调区 |
| `game.audio.*` | 音效细项 | 高级表现区 |
| `game.haptics.*` | 震动细项 | 高级表现区 |
| `game.uiEffects.*` | UI 动效细项 | 高级表现区 |
| `resources.*` | 资源档与主题档 | 高级资源管理项 |
| `debug.*` | 调试与模拟字段 | 默认不进正式后台 |

建议：

- 这一层先不要全做成常规表单
- 后期可以根据真实使用频率，把一部分下放到常用活动项

---

## 4. 当前建议的开放策略

### 4.1 先开放

优先开放这些：

- 核心必需项
- 常用活动项中的对局规则、打点规则、完赛规则、分值规则

### 4.2 后开放

后续再开放这些：

- 常用活动项中的部分设置默认值
- 少量高频使用的内容卡字段
- 少量高频使用的表现字段

### 4.3 暂不开放

建议先不开放这些：

- 大量细粒度动画参数
- 大量音效和震动细项
- 纯调试字段
- 仅研发联调使用的实验字段

---

## 5. 后续维护规则

后续每次新增配置能力时，建议先回答 3 个问题：

1. 这个字段是不是不配就跑不了？
2. 这个字段是不是活动经常会改？
3. 这个字段是不是只是研发或实验阶段才会动？

对应落点：

- 第 1 类：核心必需项
- 第 2 类：常用活动项
- 第 3 类：高级实验项

如果无法明确归类，默认先归入高级实验项，不急着开放到后台常规表单。