# 后台管理最小方案
> 文档版本：v1.1
> 最后更新：2026-04-03 11:02:42

## 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. 后台第一版页面建议

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

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

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

补充：

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

## 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 发布 的最小运营后台。