300 lines
7.0 KiB
Markdown
300 lines
7.0 KiB
Markdown
# 数据模型
|
||
> 文档版本：v1.4
|
||
> 最后更新：2026-04-03 22:34:08
|
||
|
||
当前 migration 共 11 版。
|
||
|
||
## 1. 迁移清单
|
||
|
||
- [0001_init.sql](D:/dev/cmr-mini/backend/migrations/0001_init.sql)
|
||
- [0002_launch.sql](D:/dev/cmr-mini/backend/migrations/0002_launch.sql)
|
||
- [0003_home.sql](D:/dev/cmr-mini/backend/migrations/0003_home.sql)
|
||
- [0004_results.sql](D:/dev/cmr-mini/backend/migrations/0004_results.sql)
|
||
- [0005_config_pipeline.sql](D:/dev/cmr-mini/backend/migrations/0005_config_pipeline.sql)
|
||
- [0006_resource_objects.sql](D:/dev/cmr-mini/backend/migrations/0006_resource_objects.sql)
|
||
- [0007_variant_minimal.sql](D:/dev/cmr-mini/backend/migrations/0007_variant_minimal.sql)
|
||
- [0008_production_skeleton.sql](D:/dev/cmr-mini/backend/migrations/0008_production_skeleton.sql)
|
||
- [0009_event_ops_phase2.sql](D:/dev/cmr-mini/backend/migrations/0009_event_ops_phase2.sql)
|
||
- [0010_event_default_bindings.sql](D:/dev/cmr-mini/backend/migrations/0010_event_default_bindings.sql)
|
||
- [0011_card_summary.sql](D:/dev/cmr-mini/backend/migrations/0011_card_summary.sql)
|
||
|
||
## 2. 表分组
|
||
|
||
### 2.1 多租户与入口
|
||
|
||
- `tenants`
|
||
- `entry_channels`
|
||
|
||
职责：
|
||
|
||
- 识别品牌壳
|
||
- 识别渠道入口
|
||
- 承接后续俱乐部 / 政府公众号 / H5 / 二维码入口
|
||
|
||
### 2.2 用户与登录
|
||
|
||
- `users`
|
||
- `login_identities`
|
||
- `auth_sms_codes`
|
||
- `auth_refresh_tokens`
|
||
|
||
职责：
|
||
|
||
- 平台级用户
|
||
- 多身份登录
|
||
- 验证码记录
|
||
- refresh token 持久化
|
||
|
||
当前身份示例：
|
||
|
||
- `mobile`
|
||
- `wechat_mini_openid`
|
||
- `wechat_unionid`
|
||
|
||
### 2.3 业务对象与配置发布
|
||
|
||
- `events`
|
||
- `event_releases`
|
||
|
||
职责分工：
|
||
|
||
- `events` 管业务对象身份和展示
|
||
- `event_releases` 管发布后的运行配置入口
|
||
|
||
关键字段：
|
||
|
||
- `events.current_release_id`
|
||
- `event_releases.release_public_id`
|
||
- `event_releases.config_label`
|
||
- `event_releases.manifest_url`
|
||
- `event_releases.manifest_checksum_sha256`
|
||
- `event_releases.route_code`
|
||
|
||
### 2.4 首页与入口卡片
|
||
|
||
- `cards`
|
||
|
||
职责：
|
||
|
||
- 支撑首页卡片
|
||
- 运营入口聚合
|
||
- tenant/channel 维度展示控制
|
||
- 默认体验活动标记
|
||
|
||
当前补充字段：
|
||
|
||
- `cards.is_default_experience`
|
||
|
||
当前说明：
|
||
|
||
- 活动卡片列表第一刀先通过卡片显式字段承接“默认体验活动 / 普通活动”区分
|
||
- `timeWindow / ctaText / status` 当前先由 backend 摘要层派生，不再额外新增对象层级
|
||
|
||
### 2.5 运行态
|
||
|
||
- `game_sessions`
|
||
- `session_results`
|
||
|
||
职责：
|
||
|
||
- 固化一局游戏
|
||
- 固化该局绑定的 release
|
||
- 固化局后结果摘要
|
||
|
||
### 2.6 配置构建与发布资产
|
||
|
||
- `event_config_sources`
|
||
- `event_config_builds`
|
||
- `event_release_assets`
|
||
|
||
职责：
|
||
|
||
- 保存编辑态 source config
|
||
- 保存构建后的 manifest 和 asset index
|
||
- 保存正式 release 关联的资产清单
|
||
|
||
### 2.7 共享资源对象
|
||
|
||
- `maps`
|
||
- `map_versions`
|
||
- `playfields`
|
||
- `playfield_versions`
|
||
- `resource_packs`
|
||
- `resource_pack_versions`
|
||
|
||
职责：
|
||
|
||
- 把地图、KML/赛场、内容资源包做成可复用对象
|
||
- 支撑后台第一版按“资源对象 + 版本”管理
|
||
- 给后续 event 引用组装和发布流程提供稳定边界
|
||
|
||
### 2.8 第一阶段生产骨架
|
||
|
||
- `places`
|
||
- `map_assets`
|
||
- `tile_releases`
|
||
- `course_sources`
|
||
- `course_sets`
|
||
- `course_variants`
|
||
- `map_runtime_bindings`
|
||
|
||
职责：
|
||
|
||
- 把地图运行域和活动运行绑定正式落库
|
||
- 把 KML 输入源和最终赛道方案拆开
|
||
- 在不推翻当前 `events / event_releases / game_sessions` 主链的前提下，增量补生产骨架
|
||
|
||
### 2.9 活动运营域第二阶段
|
||
|
||
- `event_presentations`
|
||
- `content_bundles`
|
||
|
||
职责：
|
||
|
||
- 把活动展示定义和内容包从临时 JSON 概念收成正式对象
|
||
- 让 `event_releases` 明确绑定：
|
||
- `presentation_id`
|
||
- `content_bundle_id`
|
||
- `runtime_binding_id`
|
||
- 保持现有 `resolvedRelease / business / variant / runtime` 稳定返回不变
|
||
|
||
### 2.10 Event 默认 active 绑定
|
||
|
||
- `events.current_presentation_id`
|
||
- `events.current_content_bundle_id`
|
||
- `events.current_runtime_binding_id`
|
||
|
||
职责：
|
||
|
||
- 固化 event 当前默认 active：
|
||
- `presentation`
|
||
- `content bundle`
|
||
- `runtime binding`
|
||
- 支撑 publish 在未显式传入时的默认继承
|
||
- 不改变前端当前稳定消费的 release / launch 字段语义
|
||
|
||
## 3. 当前最关键的关系
|
||
|
||
### `tenant -> entry_channel`
|
||
|
||
一个 tenant 下可有多个渠道入口。
|
||
|
||
### `user -> login_identity`
|
||
|
||
一个平台用户可绑定多个登录身份。
|
||
|
||
### `event -> event_release`
|
||
|
||
一个 event 可有多个 release。
|
||
|
||
客户端真正进入游戏时，最终会消费其中一份 release 的 manifest。
|
||
|
||
### `event_release -> game_session`
|
||
|
||
一局 session 必须绑定一份明确的 release。
|
||
|
||
这是当前系统最关键的配置驱动约束。
|
||
|
||
### `game_session -> session_result`
|
||
|
||
一局结束后可有一条结果摘要。
|
||
|
||
### `event_config_source -> event_config_build -> event_release`
|
||
|
||
这是后续配置生命周期主链：
|
||
|
||
- source 是编辑态
|
||
- build 是构建态
|
||
- release 是发布态
|
||
|
||
### `map -> map_version`
|
||
|
||
一张地图可有多个版本。
|
||
|
||
### `playfield -> playfield_version`
|
||
|
||
一份赛场/KML 可有多个版本。
|
||
|
||
### `resource_pack -> resource_pack_version`
|
||
|
||
一套内容/音频/主题资源可有多个版本。
|
||
|
||
### `place -> map_asset -> tile_release`
|
||
|
||
- `Place` 是地点上层对象
|
||
- `MapAsset` 是地点下的一张具体地图资产
|
||
- `TileRelease` 是某张地图的具体瓦片发布版本
|
||
|
||
### `course_source -> course_variant -> course_set`
|
||
|
||
- `CourseSource` 是原始输入源，例如 KML
|
||
- `CourseVariant` 是最终可运行赛道方案
|
||
- `CourseSet` 是一组方案集合
|
||
|
||
### `event_release -> map_runtime_binding`
|
||
|
||
- `event_releases.runtime_binding_id` 已预留给第一阶段生产骨架
|
||
- 当前客户端联调仍以 `resolvedRelease` 为主
|
||
- 第二阶段会继续把 `placeId / mapId / tileReleaseId / courseVariantId` 收到 `launch` 稳定返回中
|
||
|
||
### `event -> event_presentation`
|
||
|
||
- 一个 `event` 可有多条展示定义
|
||
- 当前最小用途是给 `event_release` 提供明确绑定目标
|
||
|
||
### `event -> content_bundle`
|
||
|
||
- 一个 `event` 可有多条内容包
|
||
- 当前最小用途是给 `event_release` 提供内容资源绑定目标
|
||
|
||
### `event_release -> presentation / content_bundle / runtime`
|
||
|
||
- 这是当前活动运营域第二阶段的最小闭环
|
||
- `release` 现在可以稳定固化：
|
||
- 展示定义
|
||
- 内容包
|
||
- 运行绑定
|
||
|
||
## 4. 当前已落库但仍应注意的边界
|
||
|
||
### 4.1 不要把玩法细节塞回事件主表
|
||
|
||
当前数据库只记录：
|
||
|
||
- 发布关系
|
||
- manifest 入口
|
||
- 结果摘要
|
||
|
||
玩法解释器仍应留在游戏客户端。
|
||
|
||
### 4.2 不要让历史局跟随当前 release 漂移
|
||
|
||
即使 event 后面发布新版本：
|
||
|
||
- 旧 session 仍然指向旧 `event_release_id`
|
||
- 旧 result 仍然对应旧 release
|
||
|
||
### 4.3 不要把登录态和运行态混在一起
|
||
|
||
当前已有两种 token：
|
||
|
||
- `access_token`
|
||
- `sessionToken`
|
||
|
||
后面如果加实时网关，也应继续区分。
|
||
|
||
## 5. 当前缺口
|
||
|
||
当前 schema 还没有这些模块：
|
||
|
||
- `competitions`
|
||
- `registrations`
|
||
- `page_configs`
|
||
- `clubs`
|
||
- `client_devices`
|
||
- 实时票据 / 网关票据
|
||
|
||
这些后面要按真正业务需要补 migration，不要先拍脑袋建大而全表。
|
||
|
||
|