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

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- a/doc/backend/后端总体架构与当前执行清单.md
+++ b/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 当前应继续围绕“活动生产与发布平台”推进，而不是回到散装配置模式。
+
+现在最该做的不是加更多零碎接口，而是做稳这三件事：
+
+- 发布完整性
+- 多赛道生产链
+- 运维后台第一期的对象与页面闭环