Add backend foundation and config-driven workbench

2026-04-01 15:01:44 +08:00
parent 88b8f05f03
commit 94a1f0ba78
68 changed files with 10833 additions and 0 deletions
--- a/backend/docs/配置管理方案.md
+++ b/backend/docs/配置管理方案.md
@@ -0,0 +1,412 @@
+# 配置管理方案
+
+## 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
+
+这样以后无论你配置项怎么继续长，主架构都还能撑住。