418 lines
7.9 KiB
Markdown
418 lines
7.9 KiB
Markdown
# 配置管理方案
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02 08:28:05
|
||
|
||
|
||
## 1. 目标
|
||
|
||
后续 backend 不应该只“管理一个 event JSON 文件”，而应该管理一整套可伸缩的配置生命周期。
|
||
|
||
这套生命周期至少要覆盖：
|
||
|
||
1. 编辑态源配置
|
||
2. 构建态中间产物
|
||
3. 对外发布版本
|
||
4. 启动时绑定的 release
|
||
5. 运行完成后的 session 追溯
|
||
|
||
核心目标不是支持当前字段，而是支持以后继续加字段时，主架构不需要推翻。
|
||
|
||
## 2. 当前现状
|
||
|
||
当前根目录下的 [event](D:/dev/cmr-mini/event) 已经保存了最小启动配置样例：
|
||
|
||
- [classic-sequential.json](D:/dev/cmr-mini/event/classic-sequential.json)
|
||
- [score-o.json](D:/dev/cmr-mini/event/score-o.json)
|
||
|
||
从这两个样例看，当前“最小启动配置”已经有了很好的雏形：
|
||
|
||
- `app`
|
||
- `map`
|
||
- `playfield`
|
||
- `game.mode`
|
||
|
||
这类文件很适合作为运行时 manifest 的基础形态。
|
||
|
||
但如果后续继续往里面堆：
|
||
|
||
- 赛事规则
|
||
- 计分规则
|
||
- 内容页
|
||
- 安全策略
|
||
- 品牌配置
|
||
- 多媒体资源
|
||
- telemetry 开关
|
||
- 实验字段
|
||
|
||
就不能再只靠单个最终 JSON 手工维护了。
|
||
|
||
## 3. 核心原则
|
||
|
||
### 3.1 稳定的是层，不是字段
|
||
|
||
后端要稳定的是这些层：
|
||
|
||
- `source config`
|
||
- `build`
|
||
- `release`
|
||
- `launch`
|
||
- `session`
|
||
|
||
而不是把所有具体配置字段都设计成强结构数据库列。
|
||
|
||
### 3.2 编辑态和运行态必须分离
|
||
|
||
编辑态：
|
||
|
||
- 配置项可以很多
|
||
- 允许草稿
|
||
- 允许试验字段
|
||
- 允许中间状态
|
||
|
||
运行态：
|
||
|
||
- 必须稳定
|
||
- 必须可校验
|
||
- 必须有版本
|
||
- 必须能被客户端直接消费
|
||
|
||
### 3.3 客户端只消费发布产物
|
||
|
||
客户端进入游戏时，不应直接读取编辑态对象。
|
||
|
||
客户端应该只消费：
|
||
|
||
- `manifest_url`
|
||
- `manifest_checksum_sha256`
|
||
- 与 manifest 配套的发布资源
|
||
|
||
### 3.4 session 必须固化 release
|
||
|
||
只要一局启动了：
|
||
|
||
- 必须固化 `event_release_id`
|
||
- 后续 event 切新发布，不影响老 session
|
||
- 结果页和历史页都必须能回看当时那份配置
|
||
|
||
## 4. 三层配置模型
|
||
|
||
## 4.1 第一层：源配置
|
||
|
||
这是编辑态配置。
|
||
|
||
建议特点：
|
||
|
||
- 允许字段增长
|
||
- 允许草稿
|
||
- 允许频繁修改
|
||
- 主要存 `jsonb`
|
||
|
||
它对应“最大启动配置”或“完整编辑配置集合”。
|
||
|
||
### 可能包含的块
|
||
|
||
- `app`
|
||
- `branding`
|
||
- `map`
|
||
- `playfield`
|
||
- `game`
|
||
- `rules`
|
||
- `scoring`
|
||
- `timeControl`
|
||
- `content`
|
||
- `assets`
|
||
- `safety`
|
||
- `telemetry`
|
||
- `featureFlags`
|
||
|
||
## 4.2 第二层：构建产物
|
||
|
||
这是后端根据源配置构建出来的中间结果。
|
||
|
||
建议职责：
|
||
|
||
- schema 校验
|
||
- 引用资源补全
|
||
- 相对路径转绝对路径
|
||
- 生成最终 manifest
|
||
- 生成资产清单
|
||
- 记录构建日志
|
||
|
||
这一层是后续做“预览构建”“草稿预览”“发布前检查”的关键。
|
||
|
||
## 4.3 第三层：发布版本
|
||
|
||
这是正式对外运行时版本。
|
||
|
||
建议职责：
|
||
|
||
- 绑定 build 结果
|
||
- 绑定 manifest URL
|
||
- 绑定 checksum
|
||
- 绑定资源清单
|
||
- 进入 launch 链路
|
||
|
||
当前已有的 `event_releases` 就是这层的起点，但后面还需要更完整的 build / assets 支撑。
|
||
|
||
## 5. 最小启动配置和最大配置怎么定义
|
||
|
||
建议不要把“最小配置 / 最大配置”当成数据库对象名，而要作为两种形态理解。
|
||
|
||
### 5.1 最小启动配置
|
||
|
||
就是客户端能开局所必需的最小 manifest。
|
||
|
||
建议包含：
|
||
|
||
- `schemaVersion`
|
||
- `releaseId`
|
||
- `app`
|
||
- `map`
|
||
- `playfield`
|
||
- `game`
|
||
- 必要资源引用
|
||
|
||
特点：
|
||
|
||
- 结构稳定
|
||
- 字段尽量少
|
||
- 客户端可直接消费
|
||
|
||
### 5.2 最大配置
|
||
|
||
就是完整编辑态 source config。
|
||
|
||
特点：
|
||
|
||
- 字段可以很多
|
||
- 块可以不断扩展
|
||
- 不要求直接给客户端消费
|
||
- 构建后才会变成运行时 manifest
|
||
|
||
## 6. 当前 event 目录该扮演什么角色
|
||
|
||
当前根目录 [event](D:/dev/cmr-mini/event) 建议继续保留，但角色要明确：
|
||
|
||
它应该是：
|
||
|
||
- 本地源配置样例目录
|
||
- 构建输入参考目录
|
||
- 调试和原型验证输入
|
||
|
||
它不应该直接承担：
|
||
|
||
- 线上唯一配置源
|
||
- 发布版本存储
|
||
- 客户端直接运行入口
|
||
|
||
线上真正的运行入口应当是：
|
||
|
||
- 数据库里的 release 元数据
|
||
- 对象存储/CDN 里的 manifest 和资源
|
||
|
||
## 7. 数据模型建议
|
||
|
||
在当前 [数据模型.md](D:/dev/cmr-mini/backend/docs/数据模型.md) 基础上，建议新增 3 张核心表。
|
||
|
||
这 3 张表的第一版 migration 已经落在：
|
||
|
||
- [0005_config_pipeline.sql](D:/dev/cmr-mini/backend/migrations/0005_config_pipeline.sql)
|
||
|
||
## 7.1 `event_config_sources`
|
||
|
||
用途：
|
||
|
||
- 存编辑态源配置版本
|
||
|
||
建议字段：
|
||
|
||
- `id`
|
||
- `event_id`
|
||
- `source_version_no`
|
||
- `source_kind`
|
||
- `schema_id`
|
||
- `schema_version`
|
||
- `status`
|
||
- `source_jsonb`
|
||
- `notes`
|
||
- `created_by_user_id`
|
||
- `created_at`
|
||
|
||
说明：
|
||
|
||
- `source_jsonb` 存完整编辑态配置
|
||
- `schema_id + schema_version` 用来做校验
|
||
|
||
## 7.2 `event_config_builds`
|
||
|
||
用途：
|
||
|
||
- 存一次构建的结果
|
||
|
||
建议字段：
|
||
|
||
- `id`
|
||
- `event_id`
|
||
- `source_id`
|
||
- `build_no`
|
||
- `build_status`
|
||
- `build_log`
|
||
- `manifest_jsonb`
|
||
- `asset_index_jsonb`
|
||
- `created_by_user_id`
|
||
- `created_at`
|
||
|
||
说明：
|
||
|
||
- `manifest_jsonb` 是构建后得到的运行 manifest
|
||
- `asset_index_jsonb` 是构建时收集到的资源清单
|
||
|
||
## 7.3 `event_release_assets`
|
||
|
||
用途：
|
||
|
||
- 存 release 的资源清单
|
||
|
||
建议字段：
|
||
|
||
- `id`
|
||
- `event_release_id`
|
||
- `asset_type`
|
||
- `asset_key`
|
||
- `asset_path`
|
||
- `asset_url`
|
||
- `checksum`
|
||
- `size_bytes`
|
||
- `meta_jsonb`
|
||
|
||
说明：
|
||
|
||
- 这张表非常适合后面做资源核对、回滚、调试和发布检查
|
||
|
||
## 8. 强结构和弱结构怎么分
|
||
|
||
## 8.1 强结构字段
|
||
|
||
这些字段后端应强约束：
|
||
|
||
- `event_id`
|
||
- `release_id`
|
||
- `manifest_url`
|
||
- `manifest_checksum_sha256`
|
||
- `status`
|
||
- `published_at`
|
||
- `session_public_id`
|
||
- `event_release_id`
|
||
|
||
这些是运行链路基础，不适合做成松散字段。
|
||
|
||
## 8.2 弱结构字段
|
||
|
||
这些字段建议主要放 `jsonb`：
|
||
|
||
- 玩法规则
|
||
- 计分策略
|
||
- 文案内容
|
||
- H5 内容块
|
||
- 品牌视觉配置
|
||
- 资源扩展配置
|
||
- feature flags
|
||
- 实验字段
|
||
|
||
这样后面新增字段时，主链路不会被迫重构。
|
||
|
||
## 9. 后端后续能力建议
|
||
|
||
## 9.1 源配置管理
|
||
|
||
建议支持：
|
||
|
||
- 保存草稿 source
|
||
- 查看 source 历史版本
|
||
- source diff
|
||
- 从文件导入 source
|
||
|
||
## 9.2 构建能力
|
||
|
||
建议支持：
|
||
|
||
- 校验 source schema
|
||
- 校验资源引用存在
|
||
- 生成 manifest
|
||
- 生成 asset index
|
||
- 输出 build log
|
||
|
||
## 9.3 发布能力
|
||
|
||
建议支持：
|
||
|
||
- 从某个 build 发布 release
|
||
- 生成 `manifest_url`
|
||
- 上传 release 资产
|
||
- 标记当前生效 release
|
||
- 回滚旧 release
|
||
|
||
## 9.4 调试能力
|
||
|
||
建议支持：
|
||
|
||
- 预览构建结果
|
||
- 查看某个 release 资产清单
|
||
- 查看某个 session 实际绑定的 release 和 manifest
|
||
|
||
## 10. 推荐 API 路线
|
||
|
||
建议后面按这个顺序补接口：
|
||
|
||
### 第一批：source
|
||
|
||
- `POST /events/{id}/config-sources`
|
||
- `GET /events/{id}/config-sources`
|
||
- `GET /config-sources/{id}`
|
||
|
||
### 第二批：build
|
||
|
||
- `POST /config-sources/{id}/build`
|
||
- `GET /builds/{id}`
|
||
- `GET /builds/{id}/manifest`
|
||
|
||
### 第三批：release
|
||
|
||
- `POST /builds/{id}/release`
|
||
- `GET /releases/{id}`
|
||
- `GET /releases/{id}/assets`
|
||
|
||
### 第四批：preview
|
||
|
||
- `GET /events/{id}/preview-play`
|
||
- `POST /builds/{id}/preview-launch`
|
||
|
||
## 11. 推荐开发顺序
|
||
|
||
当前最值得先做的不是配置后台 UI，而是配置构建器。
|
||
|
||
建议顺序：
|
||
|
||
1. 先定义 source config 和 manifest 的字段边界
|
||
2. 先建 `event_config_sources`
|
||
3. 先做 schema 校验器
|
||
4. 先做 build 产物生成
|
||
5. 再建 `event_config_builds`
|
||
6. 再做正式 release 发布
|
||
7. 最后才做后台编辑器
|
||
|
||
原因很简单：
|
||
|
||
- 没有 build/release 核心能力，后台只是个大表单
|
||
- 先把构建链打通，后面各种管理壳层才有基础
|
||
|
||
## 12. 一句话结论
|
||
|
||
后续 backend 不该做成“管理一个越来越大的 event JSON 文件”，而应该做成：
|
||
|
||
> 源配置管理 + 构建产物管理 + release 发布管理 + session 绑定 release
|
||
|
||
这样以后无论你配置项怎么继续长，主架构都还能撑住。
|
||
|
||
|