290 lines
6.2 KiB
Markdown
290 lines
6.2 KiB
Markdown
# 后端总体架构与当前执行清单
|
||
> 文档版本：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 当前应继续围绕“活动生产与发布平台”推进，而不是回到散装配置模式。
|
||
|
||
现在最该做的不是加更多零碎接口，而是做稳这三件事：
|
||
|
||
- 发布完整性
|
||
- 多赛道生产链
|
||
- 运维后台第一期的对象与页面闭环
|