zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/repo-foundation
cmr-mini/backend/docs/后台管理最小方案.md

11 KiB
Raw Permalink Blame History

后台管理最小方案

文档版本：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. 运行实例层
  • 一个活动实例始终保持：
    • 单地图
    • 单路线组
    • 单玩法
  1. 组合入口层
  • 通过组合卡片或组合入口，把多个活动实例编排成一个前台入口
  • 例如：
    • 多地图合集
    • 多玩法合集
    • 不同难度合集
    • 同主题活动合集

这样做的目的：

  • 前台入口可以灵活组合
  • 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 继续保留，但收进主流程内部，不作为首页认知入口
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 发布 的最小运营后台。

Reference in New Issue View Git Blame Copy Permalink