239 lines
5.0 KiB
Markdown
239 lines
5.0 KiB
Markdown
# 系统架构
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02 08:28:05
|
||
|
||
|
||
## 1. 目标
|
||
|
||
当前 backend 不是一个“给地图页喂数据的简单服务”，而是一个业务壳后端。
|
||
|
||
它负责：
|
||
|
||
- 用户与登录
|
||
- 多租户与多入口
|
||
- 首页与业务入口聚合
|
||
- Event 业务对象
|
||
- 配置发布解析
|
||
- 启动一局游戏
|
||
- session 生命周期
|
||
- 结果沉淀
|
||
|
||
它不负责：
|
||
|
||
- 解释游戏玩法细节
|
||
- 运行时解析复杂地图规则
|
||
- 直接下发数据库编辑态对象给客户端
|
||
|
||
补充约束：
|
||
|
||
- 这套 backend 必须服务未来 APP，不是“小程序专用后端”
|
||
- 登录方式可以按终端区分，但业务对象和业务接口不能按端分裂成两套
|
||
|
||
## 2. 分层
|
||
|
||
### 2.1 平台层
|
||
|
||
平台层统一处理：
|
||
|
||
- `tenant`
|
||
- `entry_channel`
|
||
- `user`
|
||
- `login_identity`
|
||
- `auth_refresh_token`
|
||
|
||
这层是整个平台共用能力。
|
||
|
||
它必须同时支撑：
|
||
|
||
- APP
|
||
- 微信小程序
|
||
- 后续公众号 / H5 / 其他渠道
|
||
|
||
### 2.2 业务层
|
||
|
||
业务层统一处理：
|
||
|
||
- `card`
|
||
- `event`
|
||
- `event_play`
|
||
- `entry_home`
|
||
- `profile`
|
||
|
||
它面向页面和运营入口，但不直接承载游戏规则。
|
||
|
||
### 2.3 配置发布层
|
||
|
||
配置发布层统一处理：
|
||
|
||
- `event_release`
|
||
- `manifest_url`
|
||
- `manifest_checksum_sha256`
|
||
- `route_code`
|
||
|
||
这层是“客户端真正进入游戏时要消费的运行配置入口”。
|
||
|
||
这里的发布结构应保持终端中立：
|
||
|
||
- 不写死为小程序专用结构
|
||
- 不直接依赖某个端的页面实现
|
||
- 允许 APP 和小程序共用同一份 release / manifest
|
||
|
||
### 2.4 运行层
|
||
|
||
运行层统一处理：
|
||
|
||
- `game_session`
|
||
- `session_token`
|
||
- `session_results`
|
||
|
||
这层不关心编辑态，只关心“一局游戏”。
|
||
|
||
## 3. 最重要的对象关系
|
||
|
||
### 3.1 `event`
|
||
|
||
`event` 是业务对象。
|
||
|
||
它负责：
|
||
|
||
- 活动身份
|
||
- 展示名称
|
||
- 业务状态
|
||
- 当前指向的发布版本
|
||
|
||
它不是客户端实际运行的配置文件本体。
|
||
|
||
### 3.2 `event_release`
|
||
|
||
`event_release` 是配置发布对象。
|
||
|
||
它负责：
|
||
|
||
- 这次发布的 `manifest_url`
|
||
- 配置标签 `config_label`
|
||
- 可选校验值
|
||
- 可选 `route_code`
|
||
|
||
进入游戏时，客户端真正需要的是这里。
|
||
|
||
### 3.3 `game_session`
|
||
|
||
`game_session` 是运行对象。
|
||
|
||
它必须固化：
|
||
|
||
- 当前用户
|
||
- 当前 event
|
||
- 当前实际使用的 `event_release`
|
||
- 当前 `session_token`
|
||
|
||
这样后续哪怕 event 切到新 release，旧 session 也不会漂移。
|
||
|
||
## 4. 配置驱动原则
|
||
|
||
这套系统必须坚持下面这条原则：
|
||
|
||
> 业务层先解析出一份可启动的 release，客户端再基于这份 release 的 manifest 进入游戏。
|
||
|
||
不能走成：
|
||
|
||
> 客户端拿到 event 后自己再去推断该加载哪份配置
|
||
|
||
所以当前接口都在往这个方向收口：
|
||
|
||
- `GET /events/{id}/play` 会返回 `resolvedRelease`
|
||
- `POST /events/{id}/launch` 会返回 `resolvedRelease`
|
||
- `GET /sessions/{id}` 会返回 `resolvedRelease`
|
||
- `GET /sessions/{id}/result` 能追溯到当时的 release
|
||
|
||
补充约束：
|
||
|
||
- release / manifest 只描述运行配置，不承载某个端的页面状态
|
||
- 玩家设置、设备能力差异、运行时 UI 编译由客户端自行处理
|
||
- 后端负责“发布可运行配置”，不是“替某个端生成最终运行时 profile”
|
||
|
||
## 5. 代码分层
|
||
|
||
### 5.1 入口层
|
||
|
||
- [main.go](D:/dev/cmr-mini/backend/cmd/api/main.go)
|
||
- [app.go](D:/dev/cmr-mini/backend/internal/app/app.go)
|
||
- [config.go](D:/dev/cmr-mini/backend/internal/app/config.go)
|
||
|
||
### 5.2 HTTP 层
|
||
|
||
- [router.go](D:/dev/cmr-mini/backend/internal/httpapi/router.go)
|
||
- [handlers](D:/dev/cmr-mini/backend/internal/httpapi/handlers)
|
||
- [middleware](D:/dev/cmr-mini/backend/internal/httpapi/middleware)
|
||
|
||
### 5.3 用例层
|
||
|
||
- [service](D:/dev/cmr-mini/backend/internal/service)
|
||
|
||
当前主要服务：
|
||
|
||
- `AuthService`
|
||
- `EntryService`
|
||
- `HomeService`
|
||
- `EntryHomeService`
|
||
- `EventService`
|
||
- `EventPlayService`
|
||
- `SessionService`
|
||
- `ResultService`
|
||
- `ProfileService`
|
||
- `DevService`
|
||
|
||
### 5.4 数据层
|
||
|
||
- [store/postgres](D:/dev/cmr-mini/backend/internal/store/postgres)
|
||
|
||
特点：
|
||
|
||
- 手写 SQL
|
||
- `pgx` 连接池
|
||
- 不依赖 ORM
|
||
|
||
### 5.5 平台适配层
|
||
|
||
- [jwtx](D:/dev/cmr-mini/backend/internal/platform/jwtx)
|
||
- [security](D:/dev/cmr-mini/backend/internal/platform/security)
|
||
- [wechatmini](D:/dev/cmr-mini/backend/internal/platform/wechatmini)
|
||
|
||
## 6. 当前边界
|
||
|
||
### 6.1 backend 管什么
|
||
|
||
- 业务身份
|
||
- 配置发布解析
|
||
- 启动编排
|
||
- 一局的生命周期和结果
|
||
|
||
### 6.2 游戏客户端管什么
|
||
|
||
- 下载 `manifest_url`
|
||
- 解析运行配置
|
||
- 驱动地图和玩法
|
||
- 产生过程数据和结束摘要
|
||
|
||
适用范围：
|
||
|
||
- 微信小程序客户端
|
||
- 未来 APP 客户端
|
||
|
||
也就是说：
|
||
|
||
- 后端按统一业务模型输出
|
||
- 终端差异放在客户端运行时适配层，不放在后端业务接口层
|
||
|
||
### 6.3 后续网关该怎么接
|
||
|
||
后面如果接实时网关，建议仍然走：
|
||
|
||
- backend 负责登录与 launch
|
||
- launch 或 session 负责产出短期实时票据
|
||
- 网关只认 backend 签发的运行态票据
|
||
|
||
不要把微信身份或业务 token 直接暴露给实时网关。
|
||
|
||
|