229 lines
4.5 KiB
Markdown
229 lines
4.5 KiB
Markdown
# 核心流程
|
||
|
||
## 1. 总流程
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Entry Resolve"] --> B["Auth"]
|
||
B --> C["Home / Cards"]
|
||
C --> D["Event Play"]
|
||
D --> E["Resolve Release"]
|
||
E --> F["Launch Session"]
|
||
F --> G["Client Load Manifest"]
|
||
G --> H["Session Start / Finish"]
|
||
H --> I["Result / History"]
|
||
```
|
||
|
||
补充说明：
|
||
|
||
- 这条主流程既服务当前小程序，也要服务未来 APP
|
||
- 终端差异主要体现在登录方式、设备能力和运行时 UI，不应拆成两套业务流程
|
||
|
||
## 2. 入口解析
|
||
|
||
入口层先解决：
|
||
|
||
- 用户从哪个渠道进来
|
||
- 当前归属哪个 `tenant`
|
||
- 当前品牌壳和首页卡片应该加载什么
|
||
|
||
当前对应接口：
|
||
|
||
- `GET /entry/resolve`
|
||
- `GET /home`
|
||
- `GET /cards`
|
||
- `GET /me/entry-home`
|
||
|
||
## 3. 登录流程
|
||
|
||
### 3.1 APP
|
||
|
||
APP 当前主链是手机号验证码：
|
||
|
||
1. `POST /auth/sms/send`
|
||
2. `POST /auth/login/sms`
|
||
3. 返回 `access_token + refresh_token`
|
||
|
||
说明：
|
||
|
||
- APP 是未来更强接入端，后端设计必须预留身体资料、设备绑定、遥测摘要等扩展空间
|
||
|
||
### 3.2 微信小程序
|
||
|
||
微信小程序当前主链是：
|
||
|
||
1. 客户端 `wx.login`
|
||
2. `POST /auth/login/wechat-mini`
|
||
3. 后端换取 `openid`
|
||
4. 返回 `access_token + refresh_token`
|
||
|
||
开发环境也支持 `dev-` 前缀 code。
|
||
|
||
### 3.3 绑定与合并
|
||
|
||
当小程序用户后续绑定手机号时：
|
||
|
||
1. 先发 `bind_mobile` 场景验证码
|
||
2. `POST /auth/bind/mobile`
|
||
3. 如果手机号已属于别的用户，则合并到手机号主账号
|
||
|
||
当前策略是：
|
||
|
||
- 手机号账号优先
|
||
- 微信轻账号并入手机号账号
|
||
|
||
## 4. 首页流程
|
||
|
||
首页不是固定首页，而是“入口上下文首页”。
|
||
|
||
当前聚合接口：
|
||
|
||
- `GET /me/entry-home`
|
||
|
||
它会返回：
|
||
|
||
- 当前用户
|
||
- 当前 tenant
|
||
- 当前 channel
|
||
- 当前 cards
|
||
- 继续中的 session
|
||
- 最近一局 session
|
||
|
||
## 5. Event Play 流程
|
||
|
||
活动详情页或开始前准备页不应该只拿 `event`。
|
||
|
||
它还必须拿到：
|
||
|
||
- 当前是否可启动
|
||
- 当前会落到哪份 `release`
|
||
- 是否有 ongoing session
|
||
- 当前推荐动作是什么
|
||
|
||
当前聚合接口：
|
||
|
||
- `GET /events/{eventPublicID}/play`
|
||
|
||
它会返回：
|
||
|
||
- `event`
|
||
- `release`
|
||
- `resolvedRelease`
|
||
- `play.canLaunch`
|
||
- `play.primaryAction`
|
||
- `play.launchSource`
|
||
- `play.ongoingSession`
|
||
- `play.recentSession`
|
||
|
||
## 6. Launch 流程
|
||
|
||
### 6.1 当前原则
|
||
|
||
启动一局游戏时，不是“启动一个 event”。
|
||
|
||
而是：
|
||
|
||
> 基于 event 当前可启动的 release，创建一条固化 release 的 session。
|
||
|
||
### 6.2 当前接口
|
||
|
||
- `POST /events/{eventPublicID}/launch`
|
||
|
||
当前请求体支持：
|
||
|
||
- `releaseId`
|
||
- `clientType`
|
||
- `deviceKey`
|
||
|
||
当前返回会带：
|
||
|
||
- `launch.source`
|
||
- `launch.resolvedRelease`
|
||
- `launch.config`
|
||
- `launch.business.sessionId`
|
||
- `launch.business.sessionToken`
|
||
|
||
补充约束：
|
||
|
||
- `launch` 是统一业务启动入口，不应因为 APP / 小程序差异复制两套接口
|
||
- 终端差异通过 `clientType`、`deviceKey`、后续能力声明字段处理
|
||
|
||
### 6.3 客户端应如何使用
|
||
|
||
客户端进入游戏前，应以返回中的这几项为准：
|
||
|
||
- `launch.resolvedRelease.releaseId`
|
||
- `launch.resolvedRelease.manifestUrl`
|
||
- `launch.resolvedRelease.manifestChecksumSha256`
|
||
|
||
而不是再拿 `event` 自己去猜。
|
||
|
||
## 7. Session 流程
|
||
|
||
### 7.1 当前接口
|
||
|
||
- `GET /sessions/{sessionPublicID}`
|
||
- `POST /sessions/{sessionPublicID}/start`
|
||
- `POST /sessions/{sessionPublicID}/finish`
|
||
- `GET /me/sessions`
|
||
|
||
### 7.2 鉴权模型
|
||
|
||
查询接口：
|
||
|
||
- 用 `access_token`
|
||
|
||
局内动作接口：
|
||
|
||
- 用 `sessionToken`
|
||
|
||
这保证了业务登录态和一局游戏运行态是分开的。
|
||
|
||
## 8. 结果流程
|
||
|
||
### 8.1 当前接口
|
||
|
||
- `GET /sessions/{sessionPublicID}/result`
|
||
- `GET /me/results`
|
||
|
||
### 8.2 当前 finish payload
|
||
|
||
`finish` 当前支持上传结果摘要：
|
||
|
||
- `finalDurationSec`
|
||
- `finalScore`
|
||
- `completedControls`
|
||
- `totalControls`
|
||
- `distanceMeters`
|
||
- `averageSpeedKmh`
|
||
- `maxHeartRateBpm`
|
||
|
||
### 8.3 结果页约束
|
||
|
||
结果页应该基于 session 结果查看，不应该回头去查当前 event 当前 release。
|
||
|
||
因为：
|
||
|
||
- 一个 event 未来可能发布新版本
|
||
- 历史结果必须追溯到当时真实跑过的那份 release
|
||
|
||
## 9. 当前最应该坚持的流程约束
|
||
|
||
业务主线应始终保持为：
|
||
|
||
`entry -> auth -> event play -> resolve release -> launch -> session -> result`
|
||
|
||
不要退回成：
|
||
|
||
`event -> launch -> game`
|
||
|
||
也不要走成：
|
||
|
||
`mini event -> mini launch -> mini game`
|
||
|
||
或：
|
||
|
||
`app event -> app launch -> app game`
|
||
|
||
业务接口必须保持统一，终端差异只进入上下文，不进入对象模型分叉。
|