后端总体架构与当前执行清单

文档版本：v1.0 最后更新：2026-04-07 14:08:00

本文档写给 backend 当前开发线程，目标是用一份短文档说明两件事：

当前系统总体架构已经收口到什么程度
backend 现在最该做什么，不该做什么

本文档不替代以下方案文档，而是它们的执行版摘要：

1. 当前总体架构

当前系统建议继续按以下链路理解，不要回退到“散装配置 + 临时页面”的推进方式：

地图运行域
-> 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 现在建议按以下顺序推进：

先稳发布完整性和多赛道发布链
再稳准备页地图预览支撑字段
再做运维后台第一期页面与对象关系
最后再扩高级定制项

这样可以避免：

主链还没稳就去做复杂后台 UI
生产对象还没定就提前开放全量配置

8. 一句话结论

backend 当前应继续围绕“活动生产与发布平台”推进，而不是回到散装配置模式。

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

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

后端总体架构与当前执行清单.md 6.2 KB Histórico Em bruto