优化地图交互与文档方案
This commit is contained in:
406
backend-config-management-v2.md
Normal file
406
backend-config-management-v2.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# 配置频繁变更场景下的后台管理方案
|
||||
|
||||
本文用于整理一套更适合“配置项变化很频繁”的后台方案。
|
||||
|
||||
适用前提：
|
||||
|
||||
- 配置驱动型应用
|
||||
- 游戏规则和字段会持续变化
|
||||
- PostgreSQL 作为主数据库
|
||||
- Go 作为中间层
|
||||
- 客户端最终读取静态 JSON
|
||||
|
||||
核心目标是：
|
||||
|
||||
**在保证后端稳定的前提下，让前端和玩法配置可以持续快速迭代。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心原则
|
||||
|
||||
这版方案的核心思想只有一句：
|
||||
|
||||
**后端管理“容器、版本、引用、发布”，不要深度管理每个细字段。**
|
||||
|
||||
也就是说：
|
||||
|
||||
- 后端负责管理对象关系
|
||||
- 后端负责管理版本和发布
|
||||
- 后端负责做基础校验
|
||||
- 后端尽量不要写死每个玩法里的所有字段细节
|
||||
|
||||
---
|
||||
|
||||
## 2. 总体结构
|
||||
|
||||
推荐分成 3 层：
|
||||
|
||||
### 2.1 编辑层
|
||||
后台管理系统面向的是“对象”，不是最终运行文件。
|
||||
|
||||
建议核心对象仍然是：
|
||||
|
||||
- `Map`
|
||||
- `Playfield`
|
||||
- `GameMode`
|
||||
- `ResourcePack`
|
||||
- `Event`
|
||||
|
||||
### 2.2 装配层
|
||||
Go 中间层负责：
|
||||
|
||||
- 读取对象
|
||||
- 合并引用
|
||||
- 基础校验
|
||||
- 生成最终运行态配置
|
||||
|
||||
### 2.3 发布层
|
||||
装配完成后，生成静态 JSON 上传到 OSS/CDN。
|
||||
|
||||
客户端只读取：
|
||||
- 已发布的静态配置
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据库存什么
|
||||
|
||||
数据库建议只存两类数据：
|
||||
|
||||
### 3.1 稳定元信息
|
||||
结构化列保存：
|
||||
|
||||
- `id`
|
||||
- `slug`
|
||||
- `name`
|
||||
- `status`
|
||||
- `current_version_id`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
|
||||
### 3.2 易变配置内容
|
||||
使用 `jsonb` 保存：
|
||||
|
||||
- `content_jsonb`
|
||||
|
||||
也就是说，每个对象都建议拆成：
|
||||
|
||||
- 主表
|
||||
- version 表
|
||||
|
||||
例如：
|
||||
|
||||
- `maps` / `map_versions`
|
||||
- `playfields` / `playfield_versions`
|
||||
- `game_modes` / `game_mode_versions`
|
||||
- `resource_packs` / `resource_pack_versions`
|
||||
- `events` / `event_versions`
|
||||
|
||||
这套结构最适合承接频繁变化的配置字段。
|
||||
|
||||
---
|
||||
|
||||
## 4. 为什么要用 version 表
|
||||
|
||||
配置频繁变化时，版本表非常重要：
|
||||
|
||||
- 支持草稿
|
||||
- 支持当前版
|
||||
- 支持发布版
|
||||
- 支持历史回滚
|
||||
- 支持 diff
|
||||
- 支持审计
|
||||
|
||||
如果没有版本表，配置演进到后面会越来越难控。
|
||||
|
||||
---
|
||||
|
||||
## 5. 后端真正该负责的内容
|
||||
|
||||
后端建议强管理下面这 4 件事：
|
||||
|
||||
### 5.1 对象关系
|
||||
例如：
|
||||
|
||||
- Event 引用哪个 Map
|
||||
- Event 引用哪个 Playfield
|
||||
- Event 引用哪个 GameMode
|
||||
- Event 引用哪个 ResourcePack
|
||||
|
||||
### 5.2 版本机制
|
||||
例如：
|
||||
|
||||
- 草稿
|
||||
- 当前版本
|
||||
- 发布版本
|
||||
- 回滚历史
|
||||
|
||||
### 5.3 基础校验
|
||||
只做真正稳定的校验：
|
||||
|
||||
- 顶层结构是否合法
|
||||
- 引用是否存在
|
||||
- schemaVersion 是否兼容
|
||||
- 必填对象是否齐全
|
||||
|
||||
### 5.4 发布装配
|
||||
把编辑态对象装配成最终运行态 JSON。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后端不要过度负责的内容
|
||||
|
||||
后端不要把下面这些写死：
|
||||
|
||||
- 每个玩法的小规则字段
|
||||
- 每个 HUD 开关
|
||||
- 每个实验性参数
|
||||
- 每个视觉细节配置
|
||||
- 每次快速迭代里新增的小配置项
|
||||
|
||||
这些变化太频繁，应该优先放在 `jsonb` 内容里，由前端消费。
|
||||
|
||||
一句话：
|
||||
|
||||
**后端不要成为“所有细字段的业务解释器”。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 配置校验的推荐分层
|
||||
|
||||
建议分成 3 层校验。
|
||||
|
||||
### 7.1 通用结构校验
|
||||
所有配置都校验：
|
||||
|
||||
- `schemaVersion`
|
||||
- `map`
|
||||
- `playfield`
|
||||
- `game`
|
||||
|
||||
### 7.2 公共字段校验
|
||||
只校验稳定公共字段，例如：
|
||||
|
||||
- `game.mode` 必须存在
|
||||
- `game.punch.radiusMeters > 0`
|
||||
|
||||
### 7.3 玩法校验器
|
||||
按 `game.mode` 分发，例如：
|
||||
|
||||
- `classic-sequential` validator
|
||||
- `score-o` validator
|
||||
|
||||
但这里有个重要原则：
|
||||
|
||||
**未识别字段默认允许透传。**
|
||||
|
||||
也就是说：
|
||||
- 不要因为多了一个新字段就发布失败
|
||||
- 只有破坏基础结构或关键规则时才拦截
|
||||
|
||||
---
|
||||
|
||||
## 8. 后台编辑策略
|
||||
|
||||
后台不要追求“一开始把所有字段都做成完美表单”。
|
||||
|
||||
建议分成两类：
|
||||
|
||||
### 8.1 稳定字段
|
||||
做正式表单：
|
||||
|
||||
- 名称
|
||||
- 状态
|
||||
- 模式
|
||||
- 地图引用
|
||||
- Playfield 引用
|
||||
- 资源包引用
|
||||
- 关键半径
|
||||
- 是否必须起点/终点
|
||||
|
||||
### 8.2 易变字段
|
||||
先保留模块化 JSON 编辑区：
|
||||
|
||||
- `game.sequence`
|
||||
- `game.guidance`
|
||||
- `game.visibility`
|
||||
- `game.feedback`
|
||||
- `playfield.controlOverrides`
|
||||
- 其他试验性字段
|
||||
|
||||
等这些字段稳定后，再逐步升级成正式表单。
|
||||
|
||||
这会比一开始硬做全表单更现实。
|
||||
|
||||
---
|
||||
|
||||
## 9. 推荐的发布模型
|
||||
|
||||
建议增加一层：
|
||||
|
||||
- `event_releases`
|
||||
|
||||
推荐字段：
|
||||
|
||||
- `id`
|
||||
- `event_id`
|
||||
- `event_version_id`
|
||||
- `release_no`
|
||||
- `manifest_url`
|
||||
- `published_by`
|
||||
- `published_at`
|
||||
- `status`
|
||||
|
||||
发布流程：
|
||||
|
||||
1. 后台选择某个 `event_version`
|
||||
2. Go 层装配最终配置
|
||||
3. Go 层校验
|
||||
4. 上传 OSS/CDN
|
||||
5. 写入 release 记录
|
||||
|
||||
客户端只消费：
|
||||
- 某次 release 对应的静态 JSON
|
||||
|
||||
---
|
||||
|
||||
## 10. Go 中间层的职责
|
||||
|
||||
Go 中间层建议承担 4 类职责：
|
||||
|
||||
### 10.1 装配器
|
||||
负责把：
|
||||
|
||||
- `Map`
|
||||
- `Playfield`
|
||||
- `GameMode`
|
||||
- `ResourcePack`
|
||||
- `Event Overrides`
|
||||
|
||||
装配成最终运行态配置。
|
||||
|
||||
### 10.2 校验器
|
||||
负责：
|
||||
|
||||
- 通用校验
|
||||
- 公共字段校验
|
||||
- 按玩法分发的插件式校验
|
||||
|
||||
### 10.3 发布器
|
||||
负责：
|
||||
|
||||
- 生成静态 JSON
|
||||
- 上传 OSS/CDN
|
||||
- 写入 release
|
||||
|
||||
### 10.4 预览 / Diff
|
||||
负责：
|
||||
|
||||
- 给后台看发布前的预览
|
||||
- 对比不同版本差异
|
||||
|
||||
一句话：
|
||||
|
||||
**Go 中间层本质上是配置编译器，不只是 CRUD 服务。**
|
||||
|
||||
---
|
||||
|
||||
## 11. 这套方案为什么适合当前项目
|
||||
|
||||
因为当前项目的真实情况就是：
|
||||
|
||||
- 配置字段变化快
|
||||
- 玩法在持续演进
|
||||
- 前端经常需要新增规则项
|
||||
- 客户端更适合消费静态配置
|
||||
|
||||
如果后端每次都跟着细字段改表、改结构、改接口，成本会非常高。
|
||||
|
||||
这套方案可以避免：
|
||||
|
||||
- 频繁 migration
|
||||
- 后端字段爆炸
|
||||
- 每次小字段变更都改很多 Go 代码
|
||||
|
||||
---
|
||||
|
||||
## 12. 推荐你现在就定死的原则
|
||||
|
||||
### 原则 1
|
||||
**数据库结构稳定，配置内容灵活。**
|
||||
|
||||
### 原则 2
|
||||
**后端强管理对象关系，不强管理每个细字段。**
|
||||
|
||||
### 原则 3
|
||||
**未知字段默认允许透传。**
|
||||
|
||||
### 原则 4
|
||||
**客户端消费细规则，后端负责发布与校验。**
|
||||
|
||||
### 原则 5
|
||||
**最终运行态永远是静态 JSON。**
|
||||
|
||||
---
|
||||
|
||||
## 13. 和当前目录结构的关系
|
||||
|
||||
如果当前静态目录是：
|
||||
|
||||
- `map/`
|
||||
- `kml/`
|
||||
- `event/`
|
||||
|
||||
这套可以继续保留。
|
||||
|
||||
理解方式是：
|
||||
|
||||
- 数据库 = 编辑态
|
||||
- Go 装配 = 发布态转换
|
||||
- OSS 目录 = 运行态产物
|
||||
|
||||
也就是说后台发布后，继续生成：
|
||||
|
||||
- `event/classic-sequential.json`
|
||||
- `event/score-o.json`
|
||||
- `map/...`
|
||||
- `kml/...`
|
||||
|
||||
客户端现有读取逻辑无需推翻。
|
||||
|
||||
---
|
||||
|
||||
## 14. 推荐实施顺序
|
||||
|
||||
建议按下面顺序推进：
|
||||
|
||||
### 第一步
|
||||
先建 5 个核心对象：
|
||||
|
||||
- `Map`
|
||||
- `Playfield`
|
||||
- `GameMode`
|
||||
- `ResourcePack`
|
||||
- `Event`
|
||||
|
||||
### 第二步
|
||||
为每个对象补 version 表。
|
||||
|
||||
### 第三步
|
||||
Go 中间层先做最小装配功能。
|
||||
|
||||
### 第四步
|
||||
实现发布到 OSS/CDN。
|
||||
|
||||
### 第五步
|
||||
后台逐步把稳定字段表单化。
|
||||
|
||||
### 第六步
|
||||
把易变字段继续保留为 JSON 编辑区。
|
||||
|
||||
---
|
||||
|
||||
## 15. 一句话总结
|
||||
|
||||
这套更适合频繁变化配置项的后台方案是：
|
||||
|
||||
**PostgreSQL 存“版本化对象 + jsonb 内容”，Go 中间层做“装配 + 校验 + 发布”，客户端只读静态发布结果。**
|
||||
Reference in New Issue
Block a user