# 核心流程
> 文档版本：v1.3
> 最后更新：2026-04-03 18:16:19


## 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`
- 当前是否存在多赛道 `variant` 编排
- 是否有 ongoing session
- 当前推荐动作是什么

补充规则：

- `play.canLaunch` 不是“有 event 就能进”
- 它当前表示“当前发布 release 已完整可启动”
- 最小要求为：
  - 已发布 release 存在
  - manifest 存在
  - runtime 已绑定
  - presentation 已绑定
  - content bundle 已绑定

当前聚合接口：

- `GET /events/{eventPublicID}/play`

它会返回：

- `event`
- `release`
- `resolvedRelease`
- `currentPresentation`
- `currentContentBundle`
- `play.assignmentMode`
- `play.courseVariants[]`
- `play.canLaunch`
- `play.primaryAction`
- `play.launchSource`
- `play.ongoingSession`
- `play.recentSession`

当前多赛道第一阶段约束：

- `play.assignmentMode` 只先支持最小口径：
  - `manual`
  - `random`
  - `server-assigned`
- `play.courseVariants[]` 只先返回准备页必需字段：
  - `id`
  - `name`
  - `description`
  - `routeCode`
  - `selectable`

## 6. Launch 流程

### 6.1 当前原则

启动一局游戏时，不是“启动一个 event”。

而是：

> 基于 event 当前可启动的 release，创建一条固化 release 的 session。

### 6.2 当前接口

- `POST /events/{eventPublicID}/launch`

当前请求体支持：

- `releaseId`
- `variantId`
- `clientType`
- `deviceKey`

当前返回会带：

- `launch.source`
- `launch.resolvedRelease`
- `launch.variant`
- `launch.presentation`
- `launch.contentBundle`
- `launch.config`
- `launch.business.sessionId`
- `launch.business.sessionToken`

补充约束：

- `launch` 是统一业务启动入口，不应因为 APP / 小程序差异复制两套接口
- 终端差异通过 `clientType`、`deviceKey`、后续能力声明字段处理

### 6.3 客户端应如何使用

客户端进入游戏前，应以返回中的这几项为准：

- `launch.resolvedRelease.releaseId`
- `launch.resolvedRelease.manifestUrl`
- `launch.resolvedRelease.manifestChecksumSha256`
- `launch.variant.id`
- `launch.variant.assignmentMode`

活动运营域第二阶段第二刀新增建议消费摘要：

- `launch.presentation.presentationId`
- `launch.contentBundle.contentBundleId`

补充说明：

- 如果活动声明了多赛道 variant，`launch` 会返回本局最终绑定的 `variant`
- 前端可以发起选择，但最终绑定以后端 `launch` 返回为准
- 故障恢复不重新分配 variant

而不是再拿 `event` 自己去猜。

## 7. Session 流程

### 7.1 当前接口

- `GET /sessions/{sessionPublicID}`
- `POST /sessions/{sessionPublicID}/start`
- `POST /sessions/{sessionPublicID}/finish`
- `GET /me/sessions`

### 7.2 鉴权模型

查询接口：

- 用 `access_token`

局内动作接口：

- 用 `sessionToken`

这保证了业务登录态和一局游戏运行态是分开的。

### 7.3 当前状态语义

- `launched`：已创建一局，客户端尚未正式开始
- `running`：客户端已开始本局
- `finished`：正常完成
- `failed`：超时或规则失败
- `cancelled`：主动退出或放弃恢复

补充约束：

- `cancelled` 和 `failed` 都不再作为 ongoing session 返回
- “放弃恢复”当前正式收口为 `finish(cancelled)`
- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
- 第一阶段若活动声明了多赛道，session 会固化：
  - `assignmentMode`
  - `variantId`
  - `variantName`
  - `routeCode`

### 7.4 幂等要求

- `start` 幂等：
  - `launched` -> `running`
  - 重复 `start` 不应报错
- `finish` 幂等：
  - 第一次进入终态后，重复 `finish` 直接返回当前结果
- 这个约束同时服务小程序故障恢复和未来 APP 重试补报

## 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
- 如果一场活动存在多个 variant，结果与历史摘要也必须能追溯本局 `variantId`

## 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`

业务接口必须保持统一，终端差异只进入上下文，不进入对象模型分叉。