458 lines
11 KiB
Markdown
458 lines
11 KiB
Markdown
# 后台管理最小方案
|
||
> 文档版本：v1.8
|
||
> 最后更新：2026-04-07 17:23:15
|
||
|
||
## 1. 目标
|
||
|
||
后台第一版不是做一个“大而全配置表单”，而是先做一套最小可运营壳，解决这 3 个问题：
|
||
|
||
1. 共享资源能被对象化管理
|
||
2. `event` 能引用这些资源并组装配置
|
||
3. 能从 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. 后台第一版页面建议
|
||
|
||
按当前运维工作流，建议先按“地图主流程”组织，而不是把底层对象散着摆：
|
||
|
||
1. 地图列表页
|
||
2. 地图详情页
|
||
3. KML / 赛道管理页
|
||
4. 活动管理页
|
||
5. 发布中心
|
||
6. 资源总览页
|
||
|
||
这 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 组合入口层原则
|
||
|
||
多地图、多路线组、多玩法这类需求后面仍然会存在，但当前建议放在“组合入口层”解决，不直接进入单个活动的运行模型。
|
||
|
||
也就是分成两层：
|
||
|
||
1. 运行实例层
|
||
- 一个活动实例始终保持：
|
||
- `单地图`
|
||
- `单路线组`
|
||
- `单玩法`
|
||
|
||
2. 组合入口层
|
||
- 通过组合卡片或组合入口，把多个活动实例编排成一个前台入口
|
||
- 例如：
|
||
- 多地图合集
|
||
- 多玩法合集
|
||
- 不同难度合集
|
||
- 同主题活动合集
|
||
|
||
这样做的目的：
|
||
|
||
- 前台入口可以灵活组合
|
||
- backend 的发布、回溯、结果沉淀仍然保持简单
|
||
- 运维后台第一期不需要一开始就做复杂多对多编排器
|
||
- 后面若要扩能力，也是在“组合层”扩，而不是把底层活动模型搞乱
|
||
|
||
## 6. 一条完整后台工作流
|
||
|
||
## 7. 运维入口第一期
|
||
|
||
当前已经开始落地一条“先运维录入、再活动绑定发布”的最小入口，不再只靠手工脚本或改代码上传资源。
|
||
|
||
第一期先开放两条：
|
||
|
||
1. `POST /admin/ops/tile-releases/import`
|
||
- 作用：一次录入 `place + map asset + tile release`
|
||
- 适合把地图瓦片版本登记进 backend
|
||
|
||
2. `POST /admin/ops/course-sets/import-kml-batch`
|
||
- 作用：一次录入一组 KML，生成 `course set + variants`
|
||
- 适合多赛道活动的批量路线导入
|
||
|
||
第一期边界：
|
||
|
||
- 只做录入
|
||
- 只做对象登记和最小 current 绑定
|
||
- 已开始落地独立运维后台 `/admin/ops-workbench`
|
||
- 不替代后续完整运维后台
|
||
|
||
当前第一版页面结构已经按主流程拆成：
|
||
|
||
1. `资源总览`
|
||
2. `地图管理`
|
||
3. `资源录入`
|
||
4. `KML / 赛道管理`
|
||
5. `活动管理`
|
||
6. `发布中心`
|
||
|
||
当前设计原则：
|
||
|
||
- 运维首先看到“地图列表”
|
||
- KML / 赛道围绕地图管理，不作为孤立对象平铺
|
||
- 活动管理围绕地图关联活动、默认体验活动和发布状态展开
|
||
- 活动编排当前先按“单地图 + 单路线组 + 单玩法”收口
|
||
- 多地图 / 多玩法需求当前先通过“组合卡片 / 组合入口”承接
|
||
- 地图、KML、活动尽量统一成“列表 / 新增 / 修改 / 详情 / 预览 / 发布关联”的相似使用习惯
|
||
- 底层对象如 `Place / MapAsset / TileRelease / CourseSource / CourseSet` 继续保留，但收进主流程内部，不作为首页认知入口
|
||
|
||
```mermaid
|
||
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. 建议开发顺序
|
||
|
||
建议按下面顺序推进：
|
||
|
||
1. 先补资源对象模型和接口
|
||
2. 再补 Event 引用组装接口
|
||
3. 再补 Build / Release 运营接口
|
||
4. 最后再做后台页面
|
||
|
||
原因：
|
||
|
||
- 没有稳定后端对象模型，后台页面会反复推翻
|
||
- 先把对象和发布链条定住，前后端才不会互相拖拽
|
||
|
||
当前进度：
|
||
|
||
1. 资源对象模型和 `/admin/maps`、`/admin/playfields`、`/admin/resource-packs` 已完成
|
||
2. `Event` 组装接口 `/admin/events`、`/admin/events/{id}/source` 已完成
|
||
3. `pipeline/build/publish` 后台聚合接口已完成
|
||
4. `rollback` 已完成
|
||
5. 运维入口第一期已完成：
|
||
- `POST /admin/ops/tile-releases/import`
|
||
- `POST /admin/ops/course-sets/import-kml-batch`
|
||
6. 运维入口第二期已开始：
|
||
- `POST /admin/assets/upload`
|
||
- `POST /admin/assets/register-link`
|
||
- `GET /admin/assets`
|
||
- `GET /admin/assets/{assetPublicID}`
|
||
7. 运维后台第一版结构已开始落地到 `/admin/ops-workbench`：
|
||
- `资源总览`
|
||
- `资源录入`
|
||
- `赛道集管理`
|
||
- `活动绑定`
|
||
- `发布中心`
|
||
8. 下一步是继续把更多资源对象与发布细节收进这套运维台，而不是再塞回调试工作台
|
||
|
||
## 10. 一句话结论
|
||
|
||
是的，后面需要一版后台管理界面。
|
||
|
||
但第一版不应该是“配置大全编辑器”，而应该是：
|
||
|
||
> 共享资源管理 + Event 组装 + Build / Release 发布 的最小运营后台。
|
||
|