# 最大配置模板后台落地裁剪表
> 文档版本：v1.0
> 最后更新：2026-04-07 14:22:00

本文档用于把当前“最大配置模板”转换成 backend 可执行的落地裁剪表。

目标不是让 backend 1:1 支持所有字段，而是明确：

- 哪些块属于第一阶段必做
- 哪些块属于第二阶段可做
- 哪些块当前不应进入后台，继续留在程序默认值层

建议结合以下文档一起阅读：

- [当前最全配置模板](/D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
- [配置选项字典](/D:/dev/cmr-mini/doc/config/配置选项字典.md)
- [后台游戏定制支持方案](/D:/dev/cmr-mini/doc/backend/后台游戏定制支持方案.md)
- [后端第一阶段执行清单](/D:/dev/cmr-mini/doc/backend/后端第一阶段执行清单.md)

---

## 1. 总体原则

最大配置模板当前可视为“系统能力全集参考”，但 backend 不应照单全收。

建议按以下三类裁剪：

### A. 第一阶段必做

必须进入 backend，且需要正式对象化、可绑定、可发布。

### B. 第二阶段可做

建议预留，但不需要第一阶段就全部落地。可以先保留为默认值或高级区。

### C. 暂不进后台

继续留在程序默认值层、前端默认值层或调试层，当前不建议后台开放。

---

## 2. 顶层结构裁剪

### 2.1 `schemaVersion`

- 分类：A
- backend 建议：保留
- 理由：发布物结构版本必须可追踪

### 2.2 `version`

- 分类：A
- backend 建议：保留
- 理由：配置内容版本必须可追踪

### 2.3 `app`

- 分类：A
- backend 建议：进入活动层
- 理由：属于活动基础信息

### 2.4 `settings`

- 分类：B
- backend 建议：只开放少量活动级默认值和锁态
- 理由：适合做活动级系统设置默认值，但不宜第一阶段全开

### 2.5 `map`

- 分类：A
- backend 建议：进入地图运行域
- 理由：属于运行底座

### 2.6 `playfield`

- 分类：A
- backend 建议：进入地图与赛道层
- 理由：属于赛道空间对象

### 2.7 `game`

- 分类：A / B 混合
- backend 建议：玩法模板化后分层开放
- 理由：游戏规则是后台支持游戏定制的核心，但应按模板化和差异化开放

### 2.8 `resources`

- 分类：A
- backend 建议：进入运营内容层
- 理由：与 `presentation / content bundle` 绑定关系紧密

### 2.9 `debug`

- 分类：C
- backend 建议：不进正式后台
- 理由：属于联调/开发域，不是正式活动生产对象

---

## 3. 各块裁剪建议

## 3.1 `app`

### 建议第一阶段进入后台

- `app.id`
- `app.title`
- `app.locale`

### 说明

这些字段直接对应：

- 活动基本信息
- 活动标题
- 活动语言环境

属于活动层核心字段，必须进后台。

---

## 3.2 `settings`

### 第一阶段建议只开放少量活动级默认值

- `autoRotateEnabled`
- `trackDisplayMode`
- `gpsMarkerStyle`
- `showCenterScaleRuler`
- `useTrueNorth`

### 第二阶段再考虑开放

- 更多地图显示偏好
- 更多设备偏好
- 更细的锁态粒度

### 当前不建议后台开放

- 所有设置项的全量 `value/isLocked`

### 说明

`settings` 应继续遵守：

- 值可持久化
- `isLocked` 不持久化
- 锁态只在当前游戏配置生命周期内生效

所以后台第一阶段只应提供少量活动级默认值和锁态，不应做全量设置管理。

---

## 3.3 `map`

### 第一阶段必做

- `map.tiles`
- `map.mapmeta`
- `map.declination`
- `map.initialView.zoom`

### 说明

这块应完全进入地图运行域：

- `Place`
- `MapAsset`
- `TileRelease`

这些字段不应继续作为散装 JSON 长期管理。

---

## 3.4 `playfield`

### 第一阶段必做

- `playfield.kind`
- `playfield.source.type`
- `playfield.source.url`
- `playfield.CPRadius`
- `playfield.metadata.title`
- `playfield.metadata.code`

### 第一阶段建议支持

- `playfield.controlDefaults`
- `playfield.controlOverrides`
- `playfield.legDefaults`
- `playfield.legOverrides`

### 说明

这里是“活动级默认 + 单点重载”的主战场。

backend 不应只支持 `controlOverrides`，也应支持：

- `controlDefaults`
- `legDefaults`

这样后台才不会被迫为每个点单独填字段。

---

## 3.5 `game.session`

### 第一阶段必做

- `startManually`
- `requiresStartPunch`
- `requiresFinishPunch`
- `autoFinishOnLastControl`
- `minCompletedControlsBeforeFinish`
- `maxDurationSec`

### 说明

这块建议作为玩法模板和活动级差异项的一部分进入 backend。

尤其：

- 终点解锁条件
- 关门时间

都是活动定制常用项。

---

## 3.6 `game.punch`

### 第一阶段必做

- `policy`
- `radiusMeters`
- `requiresFocusSelection`

### 说明

这块直接影响：

- 顺序赛 / 积分赛
- 自动打点 / 确认打点
- 是否需要先选目标点

属于 backend 支持玩法定制的核心字段。

---

## 3.7 `game.sequence.skip`

### 第一阶段建议开放

- `enabled`
- `radiusMeters`
- `requiresConfirm`

### 说明

这块属于顺序赛核心差异项，适合进玩法模板页或活动高级规则页。

---

## 3.8 `game.scoring`

### 第一阶段必做

- `type`
- `defaultControlScore`

### 说明

积分赛与顺序赛都要用到基础分/计分逻辑，这块应进入玩法模板层。

---

## 3.9 `game.guidance`

### 第一阶段建议开放少量核心项

- `showLegs`
- `allowFocusSelection`

### 第二阶段再做

- `legAnimation`
- 其他更细 guidance 展现项

### 说明

backend 第一阶段不需要开放全部 guidance 表现细项，只需支撑“路线是否显示 / 是否允许选目标”这类活动差异。

---

## 3.10 `game.visibility`

### 第一阶段建议开放

- `revealFullPlayfieldAfterStartPunch`

### 说明

这是一个清晰且常见的活动差异项，适合后台开放。

---

## 3.11 `game.finish`

### 第一阶段建议开放

- `finishControlAlwaysSelectable`

### 说明

终点是否始终可结束，是活动差异项，特别适合在积分赛里后台控制。

---

## 3.12 `game.telemetry`

### 第一阶段建议只开放少量活动级默认项

- `age`
- `restingHeartRateBpm`
- `userWeightKg`

### 说明

这块未来会更多依赖用户身体数据接口，当前 backend 不必重做一整套复杂管理。

---

## 3.13 `game.feedback`

### 第一阶段不建议全开

### 第一阶段最多开放

- `audioProfile`
- `hapticsProfile`
- `uiEffectsProfile`

### 第二阶段再考虑

- 距离音三档参数
- 各类 loopGap/volume 细项

### 说明

反馈层参数很多，但大多数不适合第一阶段后台直接编辑。

---

## 3.14 `game.presentation`

### 第一阶段建议只开放这些方向

- 顺序赛点位样式 profile
- 积分赛点位样式 profile
- 积分赛 scoreBands
- `track.mode`
- `gpsMarker.style`

### 第二阶段再考虑

- 每个表现子字段全量可编排
- 更细的 glow / width / label 等参数

### 说明

这块当前最容易做过头。建议 backend 先支持“样式 profile / band / 模式级”配置，而不是让运营直接调几十个视觉参数。

---

## 3.15 `resources`

### 第一阶段必做

- `resources.audioProfile`
- `resources.contentProfile`
- `resources.themeProfile`

### 说明

这块应与：

- `EventPresentation`
- `ContentBundle`

一起归入运营内容层。

---

## 3.16 `debug`

### 当前不进后台

- `allowModeSwitch`
- `allowMockInput`
- `allowSimulator`

### 说明

这些字段继续留在开发联调域，不应进入正式运维后台。

---

## 4. backend 第一阶段最小落地范围

综合以上裁剪，建议 backend 第一阶段只做这些：

### 活动层

- `app.*`
- 活动状态
- 当前发布 release

### 地图与赛道层

- `map.*`
- `playfield.kind`
- `playfield.source`
- `playfield.metadata`
- `controlDefaults / controlOverrides`
- 多赛道 variant

### 玩法层

- `game.mode`
- `game.session`
- `game.punch`
- `game.sequence.skip`
- `game.scoring`
- 少量 `guidance / visibility / finish`

### 运营内容层

- `resources.*`
- `presentation`
- `content bundle`

### 发布层

- `schemaVersion`
- `version`
- 发布完整性校验

---

## 5. 当前明确不建议 backend 第一阶段落地的字段

以下字段当前建议继续留在：

- 程序默认值层
- 玩法默认值层
- 前端高级配置层

而不要第一阶段就强行做成后台表单：

- `game.feedback.audio.cues.*`
- `game.presentation.track.*` 的所有细粒度宽度/颜色/光晕参数
- `game.presentation.gpsMarker.*` 的所有细粒度品牌/动画参数
- 所有高级 label / glow / accentRing 细项
- `debug.*`

---

## 6. 一句话结论

最大配置模板应作为 backend 的“能力全集参考”，但不应 1:1 全量落地。

当前建议：

- 第一阶段做核心活动生产与发布字段
- 第二阶段做常用活动差异项
- 高级视觉/反馈/调试细项继续留在程序默认值层或高级区

这样 backend 才不会在第一阶段就跑偏成“大而全配置编辑器”。
