同步前后端联调与文档更新

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

@@ -0,0 +1,327 @@
+# 后台管理最小方案
+> 文档版本：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. 一条完整后台工作流
+
+```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. 下一步是把这批接口接进 workbench 或正式后台页面
+
+## 10. 一句话结论
+
+是的，后面需要一版后台管理界面。
+
+但第一版不应该是“配置大全编辑器”，而应该是：
+
+> 共享资源管理 + Event 组装 + Build / Release 发布 的最小运营后台。
+