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

doc/backend/后台游戏定制支持方案.md

@@ -0,0 +1,474 @@
+# 后台游戏定制支持方案
+> 文档版本：v1.0
+> 最后更新：2026-04-07 13:05:00
+
+本文档用于定义后台运维平台后续如何正式支持“游戏定制”，重点回答以下问题：
+
+- 后台应支持哪些层级的游戏定制
+- 哪些能力适合做成后台对象，哪些应继续留在程序默认值层
+- 活动、地图、赛道、玩法、展示、内容、发布之间应如何分层
+- 后台第一阶段与后续阶段应按什么顺序推进
+
+本文档是对 [运维后台第一期方案](/D:/dev/cmr-mini/doc/gameplay/运维后台第一期方案.md) 的补充，不替代第一期范围文档。前者回答“第一期做哪些后台模块”，本文档回答“后台长期如何支撑游戏定制”。
+
+---
+
+## 1. 总体结论
+
+后台后续不应做成“全量 JSON 编辑器”，而应做成一套**活动生产与发布平台**。
+
+游戏定制建议按以下 5 层支持：
+
+1. 活动层
+2. 地图与赛道层
+3. 玩法层
+4. 运营内容层
+5. 发布层
+
+这 5 层的核心原则是：
+
+- 稳定能力优先留在程序默认值层
+- 只有真实存在活动差异、且运营会改的能力才进入后台
+- 客户端最终只消费发布后的稳定产物，不直接消费后台草稿对象
+
+---
+
+## 2. 后台支持游戏定制的 5 层模型
+
+### 2.1 活动层
+
+活动层回答“这是一场什么活动”。
+
+建议后台在这一层支持：
+
+- 活动基本信息
+- 活动状态
+- 活动时间窗口
+- 默认体验活动标记
+- 当前发布 release
+- 当前是否允许进入
+- 活动卡片摘要
+
+这一层不应暴露大量技术字段，不直接暴露地图、瓦片、KML 原始对象。
+
+### 2.2 地图与赛道层
+
+地图与赛道层回答“这场活动在哪张地图、哪条赛道上运行”。
+
+建议后台支持：
+
+- 地点管理
+- 地图管理
+- 瓦片版本管理
+- KML / 原始赛道源输入
+- `CourseSet`
+- `CourseVariant`
+- 多赛道 `assignmentMode`
+- 赛道预览
+
+这一层是后续游戏定制的核心层。
+
+关键原则：
+
+- 一个活动可绑定多个 `variant`
+- 一个 `session` 最终只绑定一个 `variantId`
+- 多赛道选择、随机指定、后端指定都应以 `session` 绑定为准
+
+### 2.3 玩法层
+
+玩法层回答“这场活动按什么规则玩”。
+
+建议后台支持：
+
+- 选择玩法模板
+- 少量玩法差异项
+- 玩法高级选项
+
+不建议后台一开始就暴露底层散装字段。应继续坚持：
+
+- 程序默认值
+- 玩法默认值
+- 活动覆盖值
+
+例如可以后台开放：
+
+- 顺序赛是否允许跳点
+- 跳点是否需要确认
+- 积分赛终点解锁条件
+- 关门时间
+- 多赛道选择模式
+
+但不建议一开始开放：
+
+- HUD 细碎映射
+- 所有音效参数
+- 全量点位显示细项
+
+### 2.4 运营内容层
+
+运营内容层回答“活动如何展示、用什么内容表达”。
+
+建议后台支持：
+
+- `EventPresentation`
+- `ContentBundle`
+- 当前 active presentation
+- 当前 active content bundle
+- 绑定状态
+- 发布前完整性检查
+
+这里已经和当前前后端第二阶段联调方向一致：
+
+- `currentPresentation`
+- `currentContentBundle`
+- `launch.presentation`
+- `launch.contentBundle`
+
+建议后台在这一层承担：
+
+- 选择当前展示版本
+- 选择当前内容包版本
+- 校验是否影响 `canLaunch`
+
+### 2.5 发布层
+
+发布层回答“客户端最终实际消费什么”。
+
+建议后台支持：
+
+- source/build/release
+- 当前发布版本
+- 历史版本
+- 发布记录
+- 回滚
+- 是否完整绑定：
+  - runtime
+  - presentation
+  - content bundle
+
+客户端最终应只认：
+
+- `EventRelease`
+- `launch`
+- `manifest/config/runtime/presentation/contentBundle` 摘要
+
+---
+
+## 3. 后台对象模型建议
+
+建议后续后台围绕以下对象正式建设：
+
+- `Event`
+- `EventRelease`
+- `MapRuntimeBinding`
+- `EventPresentation`
+- `ContentBundle`
+- `Place`
+- `MapAsset`
+- `TileRelease`
+- `CourseSource`
+- `CourseSet`
+- `CourseVariant`
+- `GameTemplate`
+
+对象分工建议如下。
+
+### 3.1 Event
+
+负责活动业务壳：
+
+- 标题
+- 副标题
+- 活动类型
+- 状态
+- 默认体验标记
+- 当前 active 三元组引用
+
+### 3.2 EventRelease
+
+负责客户端正式消费版本：
+
+- `presentationId`
+- `contentBundleId`
+- `runtimeBindingId`
+- `manifestUrl`
+- `configUrl`
+- 状态
+- 发布时间
+
+### 3.3 MapRuntimeBinding
+
+负责把活动运营域和地图运行域绑定起来：
+
+- `placeId`
+- `mapId`
+- `tileReleaseId`
+- `courseSetId`
+- `courseVariantId`
+- `configReleaseId`
+
+### 3.4 EventPresentation
+
+负责活动展示与卡片/详情结构。
+
+### 3.5 ContentBundle
+
+负责活动内容、资源、动画、音频、文创素材等静态资源引用。
+
+### 3.6 GameTemplate
+
+负责玩法模板和规则层默认差异。
+
+这层的作用不是替代程序默认值，而是让后台运营在不碰底层散装字段的前提下，选择“规则骨架”。
+
+---
+
+## 4. 后台定制边界建议
+
+后台后续不要做成“所有变量都可配”，建议按 3 级开放：
+
+### 4.1 核心必需项
+
+必须在后台显式可见：
+
+- 活动
+- 当前发布 release
+- runtime binding
+- presentation
+- content bundle
+- 地图
+- 赛道
+- 玩法模板
+
+### 4.2 常用活动项
+
+适合在后台标准表单中开放：
+
+- 多赛道模式
+- 积分赛 / 顺序赛少量规则项
+- 关门时间
+- 终点解锁条件
+- 赛道预览开关
+- 展示版本选择
+- 内容包选择
+
+### 4.3 高级配置项
+
+保留为高级区或后续阶段：
+
+- 点位覆盖
+- 腿线覆盖
+- HUD 高级细项
+- 音效/震动细项
+- 复杂调试/实验开关
+
+---
+
+## 5. 建议的后台页面/模块
+
+如果后台要开始支撑游戏定制，建议最小页面结构如下：
+
+1. 活动列表页
+2. 活动详情页
+3. 运行绑定页
+4. 地图与赛道管理页
+5. 玩法模板页
+6. 展示与内容绑定页
+7. 发布记录页
+
+每页建议承担的职责：
+
+### 5.1 活动列表页
+
+- 看活动
+- 看状态
+- 看当前发布
+- 看是否可进入
+
+### 5.2 活动详情页
+
+- 活动基本信息
+- 当前发布摘要
+- 当前 active 三元组摘要
+
+### 5.3 运行绑定页
+
+- 选择地点/地图/瓦片/赛道
+- 查看当前绑定的 `runtime`
+- 查看多赛道 variant
+
+### 5.4 地图与赛道管理页
+
+- 地图资源
+- 瓦片版本
+- KML 输入
+- 赛道解析
+- variant 管理
+
+### 5.5 玩法模板页
+
+- 顺序赛 / 积分赛等玩法模板
+- 活动级规则覆盖项
+
+### 5.6 展示与内容绑定页
+
+- 选择 `presentation`
+- 选择 `content bundle`
+- 查看绑定完整性
+
+### 5.7 发布记录页
+
+- build
+- publish
+- release
+- 历史版本
+- 回滚
+
+---
+
+## 6. 发布与生产流程建议
+
+后台应优先支持“生产闭环”，而不是单独做配置编辑页。
+
+建议最小生产流程为：
+
+1. 编辑活动基础信息
+2. 绑定地图与赛道
+3. 选择玩法模板
+4. 绑定展示版本
+5. 绑定内容包
+6. 生成 preview/build
+7. 校验完整性
+8. 发布 release
+9. 绑定当前发布
+10. 客户端通过 `launch` 消费
+
+建议发布前必须检查：
+
+- 当前 release 是否存在
+- runtime 是否绑定
+- manifest 是否存在
+- presentation 是否绑定
+- content bundle 是否绑定
+
+这也应与当前 backend 已收紧的 `play.canLaunch` 语义保持一致。
+
+---
+
+## 7. 后台如何支持多赛道游戏定制
+
+多赛道是后续后台必须重点支持的一条。
+
+建议后台支持：
+
+- `assignmentMode`
+  - `manual`
+  - `random`
+  - `server-assigned`
+- variant 列表
+- 每个 variant 的：
+  - 名称
+  - routeCode
+  - 难度
+  - 是否默认
+  - 是否允许预览
+
+关键原则：
+
+- 活动层可以看多个 variant
+- `session` 最终只绑定一个 variant
+- 前端可以选择，但最终以后端 session / launch 返回为准
+
+---
+
+## 8. 后台如何支持准备页地图预览
+
+建议后台后续支持的方向不是额外维护一套完全独立的预览地图资源，而是围绕：
+
+- 正式瓦片
+- 赛道预览元数据
+- 预览级别
+
+来支持准备页地图预览。
+
+当前推荐方案已经单独写在：
+
+- [准备页地图预览方案](/D:/dev/cmr-mini/doc/gameplay/准备页地图预览方案.md)
+
+后台需要支持的最小数据包括：
+
+- 低级别底图来源
+- 预览范围
+- 预览尺寸
+- 当前 variant 的点位几何
+- 预览级别：
+  - `none`
+  - `summary`
+  - `full`
+
+---
+
+## 9. 分阶段实施建议
+
+建议后台支持游戏定制按以下顺序推进：
+
+### 第一步：发布与绑定先闭环
+
+优先做：
+
+- runtime binding
+- presentation
+- content bundle
+- release
+
+先保证“活动能正式发布、能正式进入”。
+
+### 第二步：地图与赛道管理
+
+优先做：
+
+- 地点
+- 地图
+- 瓦片版本
+- KML 输入
+- variant 管理
+
+### 第三步：玩法模板化
+
+优先做：
+
+- `GameTemplate`
+- 少量规则项开放
+
+### 第四步：多赛道与预览
+
+优先做：
+
+- 多赛道 variant
+- assignment mode
+- 准备页预览支撑字段
+
+### 第五步：再扩高级配置
+
+例如：
+
+- 点位覆盖
+- 腿线覆盖
+- HUD 高级映射
+- 复杂体验开关
+
+---
+
+## 10. 一句话结论
+
+后台下一步不应做成“配置编辑器”，而应做成一套**活动生产与发布平台**。
+
+游戏定制建议以后台五层模型推进：
+
+- 活动层
+- 地图与赛道层
+- 玩法层
+- 运营内容层
+- 发布层
+
+只要这五层分清，后续游戏定制、活动运营、多赛道、准备页预览和发布闭环都能稳定扩展。