cmr-mini/backend/docs/后台管理最小方案.md

后台管理最小方案

文档版本：v1.0 最后更新：2026-04-02 09:01:17

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
• 简介
• 状态
• 当前选用地图版本
• 当前选用赛场版本
• 当前选用资源包版本
• 当前玩法模式
• 少量覆盖项

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

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

不要第一版就开放：

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

3.5 Build / Release 管理

作用：

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

页面需要看到：

• source 列表
• build 列表
• build 状态
• release 列表
• 当前生效 release
• 发布人
• 发布时间

第一版动作：

• 从 source 生成 build
• 查看 build 产物
• 发布 build
• 回滚当前 release

4. 后台第一版页面建议

按最小闭环，建议先做 6 个页面：

1. 地图列表页
2. 赛场 / KML 列表页
3. 资源包列表页
4. Event 列表与编辑页
5. Build / Release 列表页
6. 发布详情页

这 6 页够把“资源录入 -> Event 组装 -> 发布 -> launch”跑通。

5. 对象模型建议

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

• Map
• MapVersion
• Playfield
• PlayfieldVersion
• ResourcePack
• ResourcePackVersion
• Event
• EventConfigSource
• EventConfigBuild
• EventRelease

关键原则：

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

6. 一条完整后台工作流

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. 下一步是把这批接口接进 workbench 或正式后台页面

10. 一句话结论

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

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

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