479 lines
8.8 KiB
Markdown
479 lines
8.8 KiB
Markdown
# 最大配置模板后台落地裁剪表
|
||
> 文档版本：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 才不会在第一阶段就跑偏成“大而全配置编辑器”。
|