mini-prog/backend/docs/配置管理方案.md

配置管理方案

文档版本：v1.0 最后更新：2026-04-02 08:28:05

1. 目标

后续 backend 不应该只“管理一个 event JSON 文件”，而应该管理一整套可伸缩的配置生命周期。

这套生命周期至少要覆盖：

1. 编辑态源配置
2. 构建态中间产物
3. 对外发布版本
4. 启动时绑定的 release
5. 运行完成后的 session 追溯

核心目标不是支持当前字段，而是支持以后继续加字段时，主架构不需要推翻。

2. 当前现状

当前根目录下的 event 已经保存了最小启动配置样例：

• classic-sequential.json
• 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 建议继续保留，但角色要明确：

它应该是：

• 本地源配置样例目录
• 构建输入参考目录
• 调试和原型验证输入

它不应该直接承担：

• 线上唯一配置源
• 发布版本存储
• 客户端直接运行入口

线上真正的运行入口应当是：

• 数据库里的 release 元数据
• 对象存储/CDN 里的 manifest 和资源

7. 数据模型建议

在当前 数据模型.md 基础上，建议新增 3 张核心表。

这 3 张表的第一版 migration 已经落在：

• 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

这样以后无论你配置项怎么继续长，主架构都还能撑住。