zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善后端联调链路与模拟器多通道支持

Browse Source
This commit is contained in:
zhangyan
2026-04-01 18:48:59 +08:00
parent 94a1f0ba78
commit a70dc8d5d0
51 changed files with 4037 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

589
backend/docs/资源对象与目录方案.md Normal file
View File

@@ -0,0 +1,589 @@
# 资源对象与目录方案
本文档用于把“地图复用、KML 复用、内容资源复用、配置发布”统一收成一套后端可执行方案。
目标：
- 不再把所有资源都塞进单个 `event/*.json`
- 让地图、KML、内容模板、主题资源都能独立复用
- 让 `event` 只负责“组合与覆盖”，不拥有底层资源本体
- 让 `release` 能稳定追溯当时到底用了哪一份地图、哪一份 KML、哪一套资源包
- 让同一套资源对象既能服务小程序，也能服务未来 APP
---
## 1. 设计结论
后端后续不要按“一个活动一个完整资源目录”来设计，而要按“资源对象库 + Event 组合 + Release 固化”来设计。
建议统一拆成这 5 类对象：
1. `Map`
2. `Playfield`
3. `GameMode`
4. `ResourcePack`
5. `Event`
它们的关系是：
- `Map`：地图底座
- `Playfield`：空间对象 / KML / 控制点集
- `GameMode`：玩法默认规则
- `ResourcePack`：内容、主题、音频等资源档
- `Event`：业务活动对象，只做引用与少量覆盖
最终客户端吃的仍然不是这些编辑态对象，而是：
- `Release`
- `manifest.json`
补充约束：
- manifest 必须保持终端中立
- 不要在资源对象层把目录或字段设计成“小程序专用资源包”
- APP 与小程序应共享同一套资源对象和 release 记录
---
## 2. 为什么必须这么拆
你现在遇到的核心问题不是“目录怎么摆”，而是“哪些资源会复用”。
当前最典型的复用场景：
- 同一张地图会被多个活动复用
- 同一份 KML / 控制点集会被多个活动复用
- 同一套 H5 内容模板会被多个活动复用
- 同一套主题和音频资源会被多个活动复用
如果继续按 `event -> 自己拥有所有文件` 设计，后面会出现：
- 地图重复拷贝
- KML 重复上传
- 同一资源多个活动版本不一致
- 一次资源修复需要改很多 event
- 历史 session 无法明确追溯当时使用的是哪一版资源
所以正确做法不是“每个 event 一套全量文件”，而是：
`共享资源对象 -> event 引用 -> release 固化版本`
---
## 3. 五类核心对象
## 3.1 Map
作用：
- 表示一张可复用地图底座
最少应包含：
- `code`
- `name`
- `status`
- `tiles root`
- `mapmeta`
- 可选边界、缩放、投影信息
典型场景：
- 一个公园底图
- 一张校园底图
- 一张城区底图
注意：
- `Map` 不等于某场活动
- `Map` 是共享资产
## 3.2 Playfield
作用：
- 表示一份可复用场地对象数据
最常见的承载就是：
- `KML`
- `GeoJSON`
- 控制点集
最少应包含：
- `code`
- `name`
- `kind`
- `sourceType`
- `sourceFile`
- 可选提取元数据
- 控制点数量
- 边界范围
- 是否包含起终点
注意：
- `Playfield` 是共享对象，不属于某个 event 私有
- 同一份 KML 可以被多个 event 复用
## 3.3 GameMode
作用：
- 表示一种玩法模式的默认规则对象
例如：
- `classic-sequential`
- `score-o`
最少应包含：
- `code`
- `mode`
- `defaults json`
注意：
- 它不是最终 event 配置
- 只是玩法默认值来源之一
## 3.4 ResourcePack
作用：
- 表示一套可复用资源档
当前最适合放进来的有：
- `audioProfile`
- `contentProfile`
- `themeProfile`
一个资源包内部可以包含：
- 内容模板
- H5 页面
- 图片
- 图标
- 音效
- 主题色与主题变量
## 3.5 Event
作用：
- 表示一个业务活动实例
它应该只负责：
- 引用哪个 `Map`
- 引用哪个 `Playfield`
- 引用哪个 `GameMode`
- 引用哪个 `ResourcePack`
- 叠加少量 `Event Overrides`
不要让 `Event` 负责：
- 保存整份地图资源
- 保存 KML 原件
- 承担所有玩法默认规则
- 拷贝整套资源包
---
## 4. 推荐目录结构
仓库内建议把“源资源”和“活动源配置”拆开。
推荐结构：
```text
resources/
maps/
lxcb-001/
v2026-03-30/
mapmeta.json
tiles/
playfields/
c01/
v2026-03-30/
course.kml
meta.json
resource-packs/
default-race/
v2026-03-30/
content/
content.html
audio/
theme/
game-modes/
classic-sequential/
v1/
mode.json
score-o/
v1/
mode.json
events/
evt-demo-001/
source.json
```
说明：
- `resources/` 放共享对象的源资源
- `game-modes/` 放玩法默认规则对象
- `events/` 只放活动级 source config
当前根目录 [event](D:/dev/cmr-mini/event) 可以继续保留作为过渡区，但后面建议逐步迁到：
- `events/`
- `resources/`
- `game-modes/`
---
## 5. Event Source 应该怎么写
后续 `event source` 不建议继续直接写死地图路径和 KML 路径，而应该引用对象版本。
推荐形态：
```json
{
"schemaVersion": "1",
"version": "2026.04.01",
"app": {
"id": "evt-demo-001",
"title": "积分赛示例"
},
"refs": {
"map": {
"code": "lxcb-001",
"version": "v2026-03-30"
},
"playfield": {
"code": "c01",
"version": "v2026-03-30"
},
"gameMode": {
"code": "score-o",
"version": "v1"
},
"resourcePack": {
"code": "default-race",
"version": "v2026-03-30"
}
},
"overrides": {
"game": {
"session": {
"maxDurationSec": 5400
},
"punch": {
"radiusMeters": 5
}
},
"playfield": {
"metadata": {
"title": "示例路线",
"code": "demo-001"
}
}
}
}
```
这样 `Event` 管的是：
- 引用
- 覆盖
不是：
- 全量资源路径
- 全量运行时配置
---
## 6. Manifest 生成规则
build / publish 时，Go 中间层应做装配：
`Map + Playfield + GameMode + ResourcePack + Event Overrides -> manifest.json`
最终生成给客户端的 manifest 可以保持现在的运行结构，例如：
```json
{
"schemaVersion": "1",
"releaseId": "rel_xxx",
"version": "2026.04.01",
"app": {
"id": "evt-demo-001",
"title": "积分赛示例"
},
"map": {
"tiles": "https://.../maps/lxcb-001/v2026-03-30/tiles/",
"mapmeta": "https://.../maps/lxcb-001/v2026-03-30/mapmeta.json"
},
"playfield": {
"kind": "control-set",
"source": {
"type": "kml",
"url": "https://.../playfields/c01/v2026-03-30/course.kml"
}
},
"game": {
"mode": "score-o"
},
"resources": {
"audioProfile": "default",
"contentProfile": "default",
"themeProfile": "default-race"
}
}
```
这层才是客户端真正消费的配置。
重要边界：
- 后端负责对象装配和发布
- 前端继续负责运行时 profile 编译
- 不把玩家设置和运行时状态写回发布配置
再补一条：
- 不把 APP 专属页面状态或小程序专属页面状态写进 manifest
- 如需终端能力差异，后续通过能力声明或运行时适配层处理
---
## 7. OSS / CDN 目录建议
线上目录不要再继续以：
- `gotomars/event/classic-sequential.json`
- `gotomars/event/score-o.json`
这种“玩法文件名”方式长期演进。
建议改成版本化结构：
```text
gotomars/maps/{mapCode}/{version}/...
gotomars/playfields/{playfieldCode}/{version}/...
gotomars/resource-packs/{packCode}/{version}/...
gotomars/game-modes/{modeCode}/{version}/mode.json
gotomars/event-releases/{eventPublicID}/{releasePublicID}/manifest.json
gotomars/event-releases/{eventPublicID}/{releasePublicID}/asset-index.json
```
好处：
- 共享资源独立版本化
- event release 只固化引用
- 历史 session 可以回溯
- 同一个 map / KML 修复时不会污染所有旧 release
- APP 与小程序可共用相同资源版本，不必重复发两套发布目录
---
## 8. 数据库建模建议
推荐按“主表 + version 表”建模。
建议对象：
- `maps`
- `map_versions`
- `playfields`
- `playfield_versions`
- `game_modes`
- `game_mode_versions`
- `resource_packs`
- `resource_pack_versions`
- `events`
- `event_versions`
- `event_releases`
其中：
- 主表存稳定元信息
- version 表存 `jsonb` 内容和具体资源引用
例如：
### `maps`
- `id`
- `code`
- `name`
- `status`
- `current_version_id`
### `map_versions`
- `id`
- `map_id`
- `version_code`
- `content_jsonb`
- `published_asset_root`
- `status`
### `playfields`
- `id`
- `code`
- `name`
- `kind`
- `status`
- `current_version_id`
### `playfield_versions`
- `id`
- `playfield_id`
- `version_code`
- `source_type`
- `content_jsonb`
- `asset_root`
- `status`
### `resource_packs`
- `id`
- `code`
- `name`
- `status`
- `current_version_id`
### `resource_pack_versions`
- `id`
- `resource_pack_id`
- `version_code`
- `content_jsonb`
- `asset_root`
- `status`
### `game_modes`
- `id`
- `code`
- `name`
- `status`
- `current_version_id`
### `game_mode_versions`
- `id`
- `game_mode_id`
- `version_code`
- `content_jsonb`
- `status`
### `event_versions`
- `id`
- `event_id`
- `version_code`
- `map_version_id`
- `playfield_version_id`
- `game_mode_version_id`
- `resource_pack_version_id`
- `overrides_jsonb`
- `status`
核心点：
- `Event` 不直接指向文件 URL
- `EventVersion` 指向对象版本
- `Release` 固化当时装配结果
---
## 9. 后端职责边界
后端应强管理：
- 对象关系
- 版本关系
- 引用有效性
- 发布装配
- 发布记录
后端不应强管理：
- 每个玩法的所有细字段解释
- 所有 HUD / 动画 / 实验细项的强结构化列
- 玩家运行时设置
- 玩家实时状态
同样不应做：
- 为 APP 和小程序各维护一套资源目录规范
- 为 APP 和小程序各发布一套不同语义的 event 配置
适合继续走 `jsonb` 的内容：
- `game.sequence.*`
- `game.guidance.*`
- `game.presentation.*`
- `playfield.controlOverrides.*`
- 各类实验性字段
---
## 10. 推荐实施顺序
建议不要一次重构到底，按下面顺序推进：
1. 先把概念定住
- `Map`
- `Playfield`
- `GameMode`
- `ResourcePack`
- `Event`
2. 先做文档和目录规范
3. 后端先补对象模型和 version 表草案
4. 配置构建器改成“按引用装配”
5. 发布器改成“版本化共享资源 + event release manifest”
6. 最后再做正式后台 UI
---
## 11. 当前阶段的务实建议
在完全切换到对象化模型前，当前仓库可以先这样过渡：
- 继续保留 [event](D:/dev/cmr-mini/event) 作为最小样例区
- 继续保留现有 `import-local -> preview -> publish`
- 但新的 source 设计和目录设计先按本文档收口
也就是说：
- 短期不推翻现有链路
- 中期把资源引用模型补进来
- 长期把单文件 `event/*.json` 迁到对象化配置系统
---
## 12. 一句话结论
后端资源管理的正确方向不是“每个活动一堆文件”，而是：
`共享资源对象库 + Event 引用装配 + Release 固化发布`
只有这样，地图复用、KML 复用、资源包复用、多活动发布才能长期稳定。
并且这套模型必须从一开始就兼顾未来 APP，而不是做成“小程序跑通后再重构”的临时结构。