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

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. 一句话结论
+
+后台下一步不应做成“配置编辑器”，而应做成一套**活动生产与发布平台**。
+
+游戏定制建议以后台五层模型推进：
+
+- 活动层
+- 地图与赛道层
+- 玩法层
+- 运营内容层
+- 发布层
+
+只要这五层分清，后续游戏定制、活动运营、多赛道、准备页预览和发布闭环都能稳定扩展。

doc/backend/后端总体架构与当前执行清单.md

@@ -0,0 +1,289 @@
+# 后端总体架构与当前执行清单
+> 文档版本：v1.0
+> 最后更新：2026-04-07 14:08:00
+
+本文档写给 backend 当前开发线程，目标是用一份短文档说明两件事：
+
+1. 当前系统总体架构已经收口到什么程度
+2. backend 现在最该做什么，不该做什么
+
+本文档不替代以下方案文档，而是它们的执行版摘要：
+
+- [后台生产闭环架构草案](/D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md)
+- [后台游戏定制支持方案](/D:/dev/cmr-mini/doc/backend/后台游戏定制支持方案.md)
+- [运维后台第一期方案](/D:/dev/cmr-mini/doc/gameplay/运维后台第一期方案.md)
+
+---
+
+## 1. 当前总体架构
+
+当前系统建议继续按以下链路理解，不要回退到“散装配置 + 临时页面”的推进方式：
+
+```text
+地图运行域
+-> Place / MapAsset / TileRelease
+-> CourseSource / CourseSet / CourseVariant
+-> MapRuntimeBinding
+
+活动运营域
+-> Event / EventPresentation / ContentBundle
+-> EventRelease
+
+客户端消费域
+-> event detail / play / launch / result / entry-home
+-> frontend 只消费发布后的稳定摘要
+```
+
+### 当前已经稳定的主链
+
+- `Event`
+- `EventRelease`
+- `Session`
+- `launch.runtime`
+- `currentPresentation / currentContentBundle`
+- `play.canLaunch`
+
+### 当前已经明确的原则
+
+- 客户端只消费**已发布 release**，不消费草稿
+- 进入游戏是否允许，统一以 `play.canLaunch` 为准
+- `session` 才是最终绑定运行对象和多赛道 variant 的事实来源
+- frontend 不再继续扩散式读取散装配置
+
+---
+
+## 2. backend 当前最重要的五层职责
+
+backend 后续支持游戏定制，建议继续按这五层推进：
+
+### 2.1 活动层
+
+负责：
+
+- 活动列表
+- 活动详情
+- 活动状态
+- 当前发布版本
+- 当前是否允许进入
+
+### 2.2 地图与赛道层
+
+负责：
+
+- 地点
+- 地图
+- 瓦片版本
+- KML / 赛道源输入
+- 赛道集合
+- 多赛道 variant
+
+### 2.3 玩法层
+
+负责：
+
+- 玩法模板
+- 少量可调规则项
+- 不负责暴露全量碎字段
+
+### 2.4 运营内容层
+
+负责：
+
+- `EventPresentation`
+- `ContentBundle`
+- 当前 active 绑定
+- 发布前完整性检查
+
+### 2.5 发布层
+
+负责：
+
+- build / publish / release
+- 当前发布
+- 历史版本
+- 回滚
+- 完整性校验
+
+---
+
+## 3. 当前 backend 最该做什么
+
+当前 backend 不建议继续四处补小接口，而应优先把以下 4 条生产链做稳。
+
+### 3.1 生产对象链做稳
+
+优先保证以下对象关系稳定：
+
+- `Place`
+- `MapAsset`
+- `TileRelease`
+- `CourseSource`
+- `CourseSet`
+- `CourseVariant`
+- `MapRuntimeBinding`
+- `EventPresentation`
+- `ContentBundle`
+- `EventRelease`
+
+要求：
+
+- 可创建
+- 可查询
+- 可绑定
+- 可发布
+
+### 3.2 发布完整性做稳
+
+发布链当前应继续保持：
+
+- 缺 `runtime` 不可进入
+- 缺 `presentation` 不可进入
+- 缺 `content bundle` 不可进入
+- 缺 `manifest` 不可进入
+- 缺当前发布 release 不可进入
+
+也就是：
+
+- `play.canLaunch`
+- `launch`
+
+必须共享同一套发布完整性语义。
+
+### 3.3 多赛道生产链做稳
+
+多赛道当前不是前端显示问题，而是 backend 生产链问题最容易出错的部分。
+
+backend 当前应确保：
+
+- `assignmentMode` 真正进入发布物
+- `play.courseVariants[]` 真正进入发布物
+- `preview.variants[]` 与可选 variant 一一对应
+- `launch.variant` 与最终 session 绑定一致
+
+### 3.4 准备页地图预览支撑字段做稳
+
+准备页地图预览 V1 已进入前端实现，因此 backend 当前应稳定提供：
+
+- `preview.mode`
+- `preview.baseTiles`
+- `preview.viewport`
+- `preview.variants[].controls`
+- `preview.selectedVariantId`
+
+当前前端策略是：
+
+- 底图优先仍走 manifest 正式瓦片
+- variant 点位优先走 `play.preview`
+
+所以 backend 当前重点不是改前端展示，而是确保：
+
+- variant 预览点位与正式 variant 对齐
+- preview 数据能稳定进入 `event detail / play`
+
+---
+
+## 4. 当前 frontend 已经接住的东西
+
+backend 当前可以默认前端已经稳定消费以下摘要：
+
+### 4.1 活动链
+
+- 活动列表最小卡片字段
+- 活动详情 `status / canLaunch / currentPresentation / currentContentBundle`
+- 准备页摘要
+
+### 4.2 运行链
+
+- `launch.runtime`
+- `launch.variant`
+- `launch.presentation`
+- `launch.contentBundle`
+
+### 4.3 会话链
+
+- `ongoingSession`
+- `finish(cancelled)`
+- 恢复 / 放弃恢复
+
+### 4.4 结果链
+
+- 单局结果页
+- 历史结果页
+- 首页 ongoing / recent 摘要
+
+也就是说，backend 当前新增字段时，优先考虑是否会影响以上已稳定消费链路。
+
+---
+
+## 5. backend 当前不要做什么
+
+当前阶段不建议 backend 现在优先去做：
+
+- 全量 JSON 编辑器
+- 复杂可视化后台搭建器
+- 一次性铺开所有高级配置项
+- 把 `/dev/workbench` 继续膨胀成正式后台
+- 先做复杂审核流/权限流
+
+一句话：
+
+**现在要做的是生产闭环，不是万能后台。**
+
+---
+
+## 6. 当前最小执行清单
+
+backend 当前建议只盯这份最小执行清单：
+
+### A. 发布对象完整性
+
+- [ ] `play.canLaunch` 与 `launch` 阻断语义一致
+- [ ] 发布物缺任一核心绑定时不能进入游戏
+
+### B. 多赛道
+
+- [ ] `assignmentMode` 稳定进入发布物
+- [ ] `courseVariants[]` 稳定进入发布物
+- [ ] `launch.variant` 与最终 session 一致
+
+### C. 预览
+
+- [ ] `play.preview` 稳定进入 `event detail / play`
+- [ ] `preview.variants[]` 与 variant 对齐
+- [ ] 单赛道 / 多赛道都可稳定预览
+
+### D. 运维平台第一期
+
+- [ ] 活动列表/详情
+- [ ] 运行绑定
+- [ ] 展示/内容绑定
+- [ ] 发布记录
+- [ ] 与 workbench 分工清晰
+
+---
+
+## 7. 下一步建议顺序
+
+backend 现在建议按以下顺序推进：
+
+1. 先稳发布完整性和多赛道发布链
+2. 再稳准备页地图预览支撑字段
+3. 再做运维后台第一期页面与对象关系
+4. 最后再扩高级定制项
+
+这样可以避免：
+
+- 主链还没稳就去做复杂后台 UI
+- 生产对象还没定就提前开放全量配置
+
+---
+
+## 8. 一句话结论
+
+backend 当前应继续围绕“活动生产与发布平台”推进，而不是回到散装配置模式。
+
+现在最该做的不是加更多零碎接口，而是做稳这三件事：
+
+- 发布完整性
+- 多赛道生产链
+- 运维后台第一期的对象与页面闭环

doc/backend/后端第一阶段执行清单.md

@@ -0,0 +1,202 @@
+# 后端第一阶段执行清单
+> 文档版本：v1.0
+> 最后更新：2026-04-07 14:15:00
+
+本文档是 backend 当前阶段的执行清单版说明，配合以下文档一起使用：
+
+- [后端总体架构与当前执行清单](/D:/dev/cmr-mini/doc/backend/后端总体架构与当前执行清单.md)
+- [后台游戏定制支持方案](/D:/dev/cmr-mini/doc/backend/后台游戏定制支持方案.md)
+- [后台生产闭环架构草案](/D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md)
+
+目标不是再讲架构，而是明确：
+
+- 第一阶段先做什么
+- 哪些必须做稳
+- 哪些暂时不要做
+
+---
+
+## 1. 第一阶段目标
+
+backend 第一阶段建议只完成这 4 件事：
+
+1. 发布完整性闭环
+2. 多赛道发布链稳定
+3. 准备页地图预览支撑字段稳定
+4. 运维后台第一期最小对象与页面闭环
+
+一句话：
+
+**先把活动能稳定发布、能稳定进入、能稳定多赛道、能稳定预览做稳。**
+
+---
+
+## 2. 第一阶段必须做稳的能力
+
+### 2.1 发布完整性
+
+必须保证以下条件一致：
+
+- `play.canLaunch`
+- `launch`
+- 当前发布 release 校验
+
+要求：
+
+- 缺 `runtime` 不可进入
+- 缺 `presentation` 不可进入
+- 缺 `content bundle` 不可进入
+- 缺 `manifest` 不可进入
+- 缺当前发布 release 不可进入
+
+### 2.2 多赛道发布链
+
+必须保证：
+
+- `assignmentMode` 进入发布物
+- `courseVariants[]` 进入发布物
+- `launch.variant` 与最终 session 一致
+- `preview.variants[]` 与 variant 对齐
+
+### 2.3 准备页地图预览支撑字段
+
+必须稳定提供：
+
+- `preview.mode`
+- `preview.baseTiles`
+- `preview.viewport`
+- `preview.variants[].controls`
+- `preview.selectedVariantId`
+
+### 2.4 运维后台第一期对象
+
+至少要能稳定管理：
+
+- `Event`
+- `EventRelease`
+- `MapRuntimeBinding`
+- `EventPresentation`
+- `ContentBundle`
+
+---
+
+## 3. 第一阶段建议顺序
+
+### 第一步：把发布完整性做稳
+
+先做：
+
+- `play.canLaunch` 规则统一
+- `launch` 阻断规则统一
+- release 完整性检查
+
+### 第二步：把多赛道做稳
+
+先做：
+
+- 发布物里透出 `assignmentMode`
+- 发布物里透出 `courseVariants[]`
+- `launch.variant`
+- session 最终绑定 variant
+
+### 第三步：把准备页预览支撑字段做稳
+
+先做：
+
+- `play.preview`
+- variant 预览点位
+- 单赛道 / 多赛道都可预览
+
+### 第四步：做运维后台第一期最小页
+
+先做：
+
+- 活动列表
+- 活动详情
+- 运行绑定
+- 展示/内容绑定
+- 发布记录
+
+---
+
+## 4. 第一阶段对象优先级
+
+### P0
+
+- `Event`
+- `EventRelease`
+- `MapRuntimeBinding`
+- `EventPresentation`
+- `ContentBundle`
+
+### P1
+
+- `Place`
+- `MapAsset`
+- `TileRelease`
+- `CourseSource`
+- `CourseSet`
+- `CourseVariant`
+
+### P2
+
+- `GameTemplate`
+- 高级玩法配置
+- 高级点位覆盖
+- 高级 HUD 配置
+
+---
+
+## 5. frontend 当前已经稳定消费的链路
+
+backend 当前可以默认 frontend 已经稳定消费：
+
+- 活动列表卡片最小字段
+- 活动详情 `status / canLaunch / currentPresentation / currentContentBundle`
+- 准备页摘要
+- `launch.runtime`
+- `launch.variant`
+- `launch.presentation`
+- `launch.contentBundle`
+- `ongoingSession`
+- 结果页 / 历史页活动链
+
+新增或调整接口时，优先不要打断这些链路。
+
+---
+
+## 6. 第一阶段暂时不要做什么
+
+当前阶段不建议优先做：
+
+- 全量 JSON 编辑器
+- 复杂可视化搭建器
+- 全量高级配置开放
+- 复杂审核流
+- 批量运维能力
+- 把 `/dev/workbench` 直接演化成正式后台
+
+---
+
+## 7. 第一阶段完成标准
+
+backend 第一阶段如果满足以下条件，就可以认为是“可进入第二阶段”：
+
+1. 活动发布对象完整性稳定
+2. 多赛道活动能稳定发布和进入
+3. 准备页地图预览字段稳定
+4. 运维后台第一期页面可用
+5. 前后端联调不再依赖临时 demo 修补
+
+---
+
+## 8. 一句话结论
+
+backend 第一阶段不是做“大而全后台”，而是做一套**稳定的活动生产与发布最小闭环**。
+
+当前最重要的是先做稳：
+
+- 发布完整性
+- 多赛道
+- 预览支撑字段
+- 运维后台第一期对象与页面