# 配置管理方案

## 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

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