后台管理最小方案

文档版本：v1.8 最后更新：2026-04-07 17:23:15

1. 目标

后台第一版不是做一个“大而全配置表单”，而是先做一套最小可运营壳，解决这 3 个问题：

共享资源能被对象化管理
event 能引用这些资源并组装配置
能从 source -> build -> release 完成发布

一句话：

后台第一版管理的是“资源对象 + 引用关系 + 发布流程”，不是“直接编辑一个越来越大的 JSON 文件”。

2. 设计边界

2.1 后台应该管理什么

地图对象
赛场 / KML 对象
资源包对象
Event 基础信息
Event 对资源对象的引用
Build / Release 发布记录

2.2 后台不应该一开始就做什么

把所有配置项做成一个超大表单
把玩家运行时设置也塞进发布配置
把前端运行时编译逻辑搬到后端后台
直接按 event 管理所有资源文件

2.3 与未来 APP 的关系

后台配置不是“小程序后台”，而是统一配置运营后台。

所以第一版开始就要坚持：

资源对象平台级复用
release / manifest 终端中立
同一份发布结果同时服务小程序和未来 APP

3. 第一版建议模块

3.1 地图管理

作用：

管理可复用地图对象和版本

建议字段：

地图名称
地图编码
版本号
mapmeta 文件
瓦片根路径
覆盖范围
状态
备注

第一版动作：

新建地图
新建地图版本
查看地图版本详情
停用某个版本

3.2 赛场 / KML 管理

作用：

把 KML / GeoJSON / 控制点数据做成独立可复用对象

建议字段：

赛场名称
赛场编码
版本号
原始文件
控制点数量
边界摘要
状态
备注

第一版动作：

上传 KML
新建赛场版本
查看赛场版本详情
停用某个版本

3.3 资源包管理

作用：

管理内容页、音频、主题等共享资源

建议字段：

资源包名称
资源包编码
版本号
内容页入口
音频包入口
主题配置入口
状态
备注

第一版动作：

新建资源包
新建资源包版本
查看资源包版本详情

3.4 Event 组装

作用：

管理业务活动本身，并引用共享资源对象

建议字段：

Event 名称
Event 编码 / public id
简介
状态
当前选用地图版本
当前选用赛场版本
当前选用资源包版本
当前玩法模式
少量覆盖项
展示定义（EventPresentation）
内容包（ContentBundle）

第一版只开放少量覆盖项：

标题
摘要
路线编码
玩法模式
少量规则开关

不要第一版就开放：

全量 presentation.*
全量 telemetry.*
全量 debug.*

3.5 Build / Release 管理

作用：

把 source config 变成 preview build，再发布成正式 release

页面需要看到：

source 列表
build 列表
build 状态
release 列表
当前生效 release
当前绑定的 presentation / bundle / runtime
发布人
发布时间

第一版动作：

从 source 生成 build
查看 build 产物
发布 build
回滚当前 release
查看 release 当前绑定的 presentation / bundle / runtime

4. 后台第一版页面建议

按当前运维工作流，建议先按“地图主流程”组织，而不是把底层对象散着摆：

地图列表页
地图详情页
KML / 赛道管理页
活动管理页
发布中心
资源总览页

这 6 页的目标是把“资源录入 -> 地图管理 -> 赛道管理 -> 活动绑定 -> 发布”跑通。

补充：

当前第二阶段已经把 EventPresentation 和 ContentBundle 收成正式最小对象
EventRelease 现在允许同时绑定：
- presentation
- content bundle
- runtime binding

5. 对象模型建议

后台第一版建议围绕这些对象展开：

Map
MapVersion
Playfield
PlayfieldVersion
ResourcePack
ResourcePackVersion
Event
EventConfigSource
EventConfigBuild
EventRelease

关键原则：

共享资源按对象库管理
event 只做引用和少量覆盖
release 固化具体版本引用

5.1 当前活动模型收口原则

为了让前台卡片、详情页、发布语义和运维操作都保持简单，当前活动模型先明确收成最小可玩单元：

单地图
单路线组
单玩法

也就是第一阶段一个活动只表达一件事：

在这张地图上，使用这组路线，按这一个玩法运行。

当前不建议第一阶段直接支持：

一个活动绑定多张地图
一个活动绑定多组路线
一个活动同时支持多玩法

复杂需求先通过“活动实例化”解决，而不是在一个活动里做多对多编排。例如：

地图 A + 路线组 1 + 顺序赛 = 活动 A1
地图 A + 路线组 2 + 顺序赛 = 活动 A2
地图 A + 路线组 2 + 积分赛 = 活动 A3

这样做的目的：

前台卡片逻辑简单
发布语义明确
结果追溯简单
运维后台第一期不需要一开始就做复杂配置器

后续如果确实需要复杂组合，优先考虑：

基于模板批量实例化多个活动

而不是直接把单个活动扩成多地图、多路线组、多玩法容器。

5.2 组合入口层原则

多地图、多路线组、多玩法这类需求后面仍然会存在，但当前建议放在“组合入口层”解决，不直接进入单个活动的运行模型。

也就是分成两层：

运行实例层
一个活动实例始终保持：
- 单地图
- 单路线组
- 单玩法
组合入口层
通过组合卡片或组合入口，把多个活动实例编排成一个前台入口
例如：
- 多地图合集
- 多玩法合集
- 不同难度合集
- 同主题活动合集

这样做的目的：

前台入口可以灵活组合
backend 的发布、回溯、结果沉淀仍然保持简单
运维后台第一期不需要一开始就做复杂多对多编排器
后面若要扩能力，也是在“组合层”扩，而不是把底层活动模型搞乱

6. 一条完整后台工作流

7. 运维入口第一期

当前已经开始落地一条“先运维录入、再活动绑定发布”的最小入口，不再只靠手工脚本或改代码上传资源。

第一期先开放两条：

POST /admin/ops/tile-releases/import
- 作用：一次录入 place + map asset + tile release
- 适合把地图瓦片版本登记进 backend
POST /admin/ops/course-sets/import-kml-batch
- 作用：一次录入一组 KML，生成 course set + variants
- 适合多赛道活动的批量路线导入

第一期边界：

只做录入
只做对象登记和最小 current 绑定
已开始落地独立运维后台 /admin/ops-workbench
不替代后续完整运维后台

当前第一版页面结构已经按主流程拆成：

资源总览
地图管理
资源录入
KML / 赛道管理
活动管理
发布中心

当前设计原则：

运维首先看到“地图列表”
KML / 赛道围绕地图管理，不作为孤立对象平铺
活动管理围绕地图关联活动、默认体验活动和发布状态展开
活动编排当前先按“单地图 + 单路线组 + 单玩法”收口
多地图 / 多玩法需求当前先通过“组合卡片 / 组合入口”承接
地图、KML、活动尽量统一成“列表 / 新增 / 修改 / 详情 / 预览 / 发布关联”的相似使用习惯
底层对象如 Place / MapAsset / TileRelease / CourseSource / CourseSet 继续保留，但收进主流程内部，不作为首页认知入口

flowchart LR
  A["录入地图版本"] --> D["Event 选择地图版本"]
  B["录入赛场版本"] --> D
  C["录入资源包版本"] --> D
  D --> E["保存 Source Config"]
  E --> F["生成 Preview Build"]
  F --> G["检查 Manifest / Asset Index"]
  G --> H["发布 Release"]
  H --> I["前台 Launch 使用新 Release"]

7. 第一版后端接口需求

后台真正开做前，后端最好先补齐下面这批接口：

7.1 地图对象

GET /admin/maps
POST /admin/maps
GET /admin/maps/{id}
POST /admin/maps/{id}/versions

7.2 赛场对象

GET /admin/playfields
POST /admin/playfields
GET /admin/playfields/{id}
POST /admin/playfields/{id}/versions

7.3 资源包对象

GET /admin/resource-packs
POST /admin/resource-packs
GET /admin/resource-packs/{id}
POST /admin/resource-packs/{id}/versions

7.4 Event 组装

GET /admin/events
POST /admin/events
GET /admin/events/{id}
PUT /admin/events/{id}
POST /admin/events/{id}/source

当前状态：

已实现
当前 source 组装方式是：
- 选择 map version
- 选择 playfield version
- 可选选择 resource pack version
- 传 gameModeCode
- 可传少量 overrides
- backend 直接生成一版可进入现有 build 流程的 source config

7.5 Build / Release

GET /admin/events/{id}/sources
POST /admin/sources/{id}/build
GET /admin/builds/{id}
POST /admin/builds/{id}/publish
POST /admin/events/{id}/rollback

当前状态：

已实现
当前已可用：
- GET /admin/events/{eventPublicID}/pipeline
- POST /admin/sources/{sourceID}/build
- GET /admin/builds/{buildID}
- POST /admin/builds/{buildID}/publish
- POST /admin/events/{eventPublicID}/rollback
当前 rollback 方式：
- 显式传 releaseId
- 只允许切回同一 event 下的已发布 release

8. 第一版不要做的事

为了避免项目被后台表单拖死，第一版明确不做：

全量 schema 可视化编辑器
拖拽式配置搭建器
复杂权限系统
资源批量编排器
多层审批流

这些都应该等“最小配置运营闭环”跑通后再说。

9. 建议开发顺序

建议按下面顺序推进：

先补资源对象模型和接口
再补 Event 引用组装接口
再补 Build / Release 运营接口
最后再做后台页面

原因：

没有稳定后端对象模型，后台页面会反复推翻
先把对象和发布链条定住，前后端才不会互相拖拽

当前进度：

资源对象模型和 /admin/maps、/admin/playfields、/admin/resource-packs 已完成
Event 组装接口 /admin/events、/admin/events/{id}/source 已完成
pipeline/build/publish 后台聚合接口已完成
rollback 已完成
运维入口第一期已完成：
- POST /admin/ops/tile-releases/import
- POST /admin/ops/course-sets/import-kml-batch
运维入口第二期已开始：
- POST /admin/assets/upload
- POST /admin/assets/register-link
- GET /admin/assets
- GET /admin/assets/{assetPublicID}
运维后台第一版结构已开始落地到 /admin/ops-workbench：
- 资源总览
- 资源录入
- 赛道集管理
- 活动绑定
- 发布中心
下一步是继续把更多资源对象与发布细节收进这套运维台，而不是再塞回调试工作台

10. 一句话结论

是的，后面需要一版后台管理界面。

但第一版不应该是“配置大全编辑器”，而应该是：

共享资源管理 + Event 组装 + Build / Release 发布的最小运营后台。

后台管理最小方案.md 11 KB Пермалинк Историја Датотека

后台管理最小方案

1. 目标

2. 设计边界

2.1 后台应该管理什么

2.2 后台不应该一开始就做什么

2.3 与未来 APP 的关系

3. 第一版建议模块

3.1 地图管理

3.2 赛场 / KML 管理

3.3 资源包管理

3.4 Event 组装

3.5 Build / Release 管理

4. 后台第一版页面建议

5. 对象模型建议

5.1 当前活动模型收口原则

5.2 组合入口层原则

6. 一条完整后台工作流

7. 运维入口第一期

7. 第一版后端接口需求

7.1 地图对象

7.2 赛场对象

7.3 资源包对象

7.4 Event 组装

7.5 Build / Release

8. 第一版不要做的事

9. 建议开发顺序

10. 一句话结论

后台管理最小方案.md 11 KB

Пермалинк Историја Датотека