Add backend foundation and config-driven workbench

backend/docs/核心流程.md

@@ -0,0 +1,204 @@
+# 核心流程
+
+## 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"]
+```
+
+## 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`
+
+### 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`
+
+### 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`