推进活动系统最小成品闭环与游客体验

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- a/doc/config/最大配置模板后台落地裁剪表.md
+++ b/doc/config/最大配置模板后台落地裁剪表.md
@@ -0,0 +1,478 @@
+# 最大配置模板后台落地裁剪表
+> 文档版本：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 才不会在第一阶段就跑偏成“大而全配置编辑器”。
--- a/doc/config/配置文档索引.md
+++ b/doc/config/配置文档索引.md
@@ -1,6 +1,6 @@
 # 配置文档索引
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.1
+> 最后更新：2026-04-07 14:22:00


 本文档用于汇总当前项目所有与配置设计、配置样例、配置管理相关的文档，并按“公共配置”和“按游戏分类”两层组织。
@@ -17,6 +17,8 @@
  最小通用骨架
 - [当前最全配置模板](D:/dev/cmr-mini/doc/config/当前最全配置模板.md)
  当前共享全量模板
+- [最大配置模板后台落地裁剪表](D:/dev/cmr-mini/doc/config/最大配置模板后台落地裁剪表.md)
+  把全量模板裁成 backend 第一阶段、第二阶段和暂不开放三类
 - [后台配置管理方案V2](D:/dev/cmr-mini/doc/config/后台配置管理方案V2.md)
  后台管理与发布方案
 - [配置发布说明](D:/dev/cmr-mini/doc/config/配置发布说明.md)