mini-prog/backend/docs/系统架构.md

系统架构

文档版本：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
• app.go
• config.go

5.2 HTTP 层

• router.go
• handlers
• middleware

5.3 用例层

• service

当前主要服务：

• AuthService
• EntryService
• HomeService
• EntryHomeService
• EventService
• EventPlayService
• SessionService
• ResultService
• ProfileService
• DevService

5.4 数据层

• store/postgres

特点：

• 手写 SQL
• pgx 连接池
• 不依赖 ORM

5.5 平台适配层

• jwtx
• security
• wechatmini

6. 当前边界

6.1 backend 管什么

• 业务身份
• 配置发布解析
• 启动编排
• 一局的生命周期和结果

6.2 游戏客户端管什么

• 下载 manifest_url
• 解析运行配置
• 驱动地图和玩法
• 产生过程数据和结束摘要

适用范围：

• 微信小程序客户端
• 未来 APP 客户端

也就是说：

• 后端按统一业务模型输出
• 终端差异放在客户端运行时适配层，不放在后端业务接口层

6.3 后续网关该怎么接

后面如果接实时网关，建议仍然走：

• backend 负责登录与 launch
• launch 或 session 负责产出短期实时票据
• 网关只认 backend 签发的运行态票据

不要把微信身份或业务 token 直接暴露给实时网关。