最大配置模板后台落地裁剪表

文档版本：v1.0 最后更新：2026-04-07 14:22:00

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

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

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

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

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 才不会在第一阶段就跑偏成“大而全配置编辑器”。

最大配置模板后台落地裁剪表.md 8.8 KB Link permanente Histórico Raw

最大配置模板后台落地裁剪表

1. 总体原则

A. 第一阶段必做

B. 第二阶段可做

C. 暂不进后台

2. 顶层结构裁剪

2.1 schemaVersion

2.2 version

2.3 app

2.4 settings

2.5 map

2.6 playfield

2.7 game

2.8 resources

2.9 debug

3. 各块裁剪建议

3.1 app

建议第一阶段进入后台

说明

3.2 settings

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

第二阶段再考虑开放

当前不建议后台开放

说明

3.3 map

第一阶段必做

说明

3.4 playfield

第一阶段必做

第一阶段建议支持

说明

3.5 game.session

第一阶段必做

说明

3.6 game.punch

第一阶段必做

说明

3.7 game.sequence.skip

第一阶段建议开放

说明

3.8 game.scoring

第一阶段必做

说明

3.9 game.guidance

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

第二阶段再做

说明

3.10 game.visibility

第一阶段建议开放

说明

3.11 game.finish

第一阶段建议开放

说明

3.12 game.telemetry

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

说明

3.13 game.feedback

第一阶段不建议全开

第一阶段最多开放

第二阶段再考虑

说明

3.14 game.presentation

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

第二阶段再考虑

说明

3.15 resources

第一阶段必做

说明

3.16 debug

当前不进后台

说明

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

活动层

地图与赛道层

玩法层

运营内容层

发布层

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

6. 一句话结论

最大配置模板后台落地裁剪表.md 8.8 KB

Link permanente Histórico Raw

2.1 `schemaVersion`

2.2 `version`

2.3 `app`

2.4 `settings`

2.5 `map`

2.6 `playfield`

2.7 `game`

2.8 `resources`

2.9 `debug`

3.1 `app`

3.2 `settings`

3.3 `map`

3.4 `playfield`

3.5 `game.session`

3.6 `game.punch`

3.7 `game.sequence.skip`

3.8 `game.scoring`

3.9 `game.guidance`

3.10 `game.visibility`

3.11 `game.finish`

3.12 `game.telemetry`

3.13 `game.feedback`

3.14 `game.presentation`

3.15 `resources`

3.16 `debug`