# 后端总体架构与当前执行清单
> 文档版本：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 当前应继续围绕“活动生产与发布平台”推进，而不是回到散装配置模式。

现在最该做的不是加更多零碎接口，而是做稳这三件事：

- 发布完整性
- 多赛道生产链
- 运维后台第一期的对象与页面闭环