mini-prog/doc/backend-config-management-v2.md

配置频繁变更场景下的后台管理方案

本文用于整理一套更适合“配置项变化很频繁”的后台方案。

适用前提：

• 配置驱动型应用
• 游戏规则和字段会持续变化
• 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 中间层做“装配 + 校验 + 发布”，客户端只读静态发布结果。