426 lines
4.9 KiB
Markdown
426 lines
4.9 KiB
Markdown
# API 清单
|
|
|
|
本文档只记录当前 backend 已实现接口，不写未来规划接口。
|
|
|
|
## 1. Health
|
|
|
|
### `GET /healthz`
|
|
|
|
用途：
|
|
|
|
- 健康检查
|
|
|
|
## 2. Auth
|
|
|
|
### `POST /auth/sms/send`
|
|
|
|
用途：
|
|
|
|
- 发登录验证码
|
|
- 发绑定手机号验证码
|
|
|
|
核心参数：
|
|
|
|
- `countryCode`
|
|
- `mobile`
|
|
- `clientType`
|
|
- `deviceKey`
|
|
- `scene`
|
|
|
|
### `POST /auth/login/sms`
|
|
|
|
用途：
|
|
|
|
- APP 手机号验证码登录
|
|
|
|
返回重点：
|
|
|
|
- `user`
|
|
- `tokens.accessToken`
|
|
- `tokens.refreshToken`
|
|
|
|
### `POST /auth/login/wechat-mini`
|
|
|
|
用途：
|
|
|
|
- 微信小程序登录
|
|
|
|
开发态：
|
|
|
|
- 支持 `dev-` 前缀 code
|
|
|
|
### `POST /auth/bind/mobile`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 已登录用户绑定手机号
|
|
- 必要时执行账号合并
|
|
|
|
### `POST /auth/refresh`
|
|
|
|
用途：
|
|
|
|
- 刷新 access token
|
|
|
|
### `POST /auth/logout`
|
|
|
|
用途：
|
|
|
|
- 撤销 refresh token
|
|
|
|
## 3. Entry / Home
|
|
|
|
### `GET /entry/resolve`
|
|
|
|
用途：
|
|
|
|
- 解析当前入口归属哪个 tenant / channel
|
|
|
|
查询参数：
|
|
|
|
- `channelCode`
|
|
- `channelType`
|
|
- `platformAppId`
|
|
- `tenantCode`
|
|
|
|
### `GET /home`
|
|
|
|
用途：
|
|
|
|
- 返回入口首页卡片
|
|
|
|
### `GET /cards`
|
|
|
|
用途：
|
|
|
|
- 只返回卡片列表
|
|
|
|
### `GET /me/entry-home`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 首页聚合接口
|
|
|
|
返回重点：
|
|
|
|
- `user`
|
|
- `tenant`
|
|
- `channel`
|
|
- `cards`
|
|
- `ongoingSession`
|
|
- `recentSession`
|
|
|
|
## 4. Event
|
|
|
|
### `GET /events/{eventPublicID}`
|
|
|
|
用途：
|
|
|
|
- Event 详情
|
|
|
|
返回重点：
|
|
|
|
- `event`
|
|
- `release`
|
|
- `resolvedRelease`
|
|
|
|
### `GET /events/{eventPublicID}/play`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 活动详情页 / 开始前准备页聚合
|
|
|
|
返回重点：
|
|
|
|
- `event`
|
|
- `release`
|
|
- `resolvedRelease`
|
|
- `play.canLaunch`
|
|
- `play.primaryAction`
|
|
- `play.launchSource`
|
|
- `play.ongoingSession`
|
|
- `play.recentSession`
|
|
|
|
### `POST /events/{eventPublicID}/launch`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 基于当前 event 的可启动 release 创建一局 session
|
|
|
|
请求体重点：
|
|
|
|
- `releaseId`
|
|
- `clientType`
|
|
- `deviceKey`
|
|
|
|
返回重点：
|
|
|
|
- `launch.source`
|
|
- `launch.resolvedRelease`
|
|
- `launch.config`
|
|
- `launch.business.sessionId`
|
|
- `launch.business.sessionToken`
|
|
|
|
### `GET /events/{eventPublicID}/config-sources`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查看某个 event 的 source config 列表
|
|
|
|
### `GET /config-sources/{sourceID}`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查看单条 source config 明细
|
|
|
|
### `GET /config-builds/{buildID}`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查看单次 build 明细
|
|
|
|
## 5. Session
|
|
|
|
### `GET /sessions/{sessionPublicID}`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查询一局详情
|
|
|
|
返回重点：
|
|
|
|
- `session`
|
|
- `event`
|
|
- `resolvedRelease`
|
|
|
|
### `POST /sessions/{sessionPublicID}/start`
|
|
|
|
鉴权：
|
|
|
|
- `sessionToken`
|
|
|
|
用途：
|
|
|
|
- 将 session 从 `launched` 推进到 `running`
|
|
|
|
### `POST /sessions/{sessionPublicID}/finish`
|
|
|
|
鉴权：
|
|
|
|
- `sessionToken`
|
|
|
|
用途：
|
|
|
|
- 结束一局
|
|
- 同时沉淀结果摘要
|
|
|
|
请求体重点：
|
|
|
|
- `sessionToken`
|
|
- `status`
|
|
- `summary.finalDurationSec`
|
|
- `summary.finalScore`
|
|
- `summary.completedControls`
|
|
- `summary.totalControls`
|
|
- `summary.distanceMeters`
|
|
- `summary.averageSpeedKmh`
|
|
- `summary.maxHeartRateBpm`
|
|
|
|
### `GET /me/sessions`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查询用户最近 session
|
|
|
|
## 6. Result
|
|
|
|
### `GET /sessions/{sessionPublicID}/result`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查询单局结果页数据
|
|
|
|
返回重点：
|
|
|
|
- `session`
|
|
- `result`
|
|
|
|
`session` 中会带：
|
|
|
|
- `releaseId`
|
|
- `configLabel`
|
|
|
|
### `GET /me/results`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 查询用户最近结果列表
|
|
|
|
## 7. Profile
|
|
|
|
### `GET /me`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- 当前用户基础信息
|
|
|
|
### `GET /me/profile`
|
|
|
|
鉴权：
|
|
|
|
- Bearer token
|
|
|
|
用途：
|
|
|
|
- “我的页”聚合接口
|
|
|
|
返回重点：
|
|
|
|
- `user`
|
|
- `bindings`
|
|
- `recentSessions`
|
|
|
|
## 8. Dev
|
|
|
|
### `POST /dev/bootstrap-demo`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 自动准备 demo tenant / channel / event / release / card
|
|
|
|
### `GET /dev/workbench`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 后端自带 API 测试面板
|
|
|
|
当前支持：
|
|
|
|
- bootstrap
|
|
- auth
|
|
- entry/home
|
|
- event/play/launch
|
|
- session start/finish/detail
|
|
- result 查询
|
|
- profile 查询
|
|
- quick flows
|
|
- scenarios
|
|
- request history
|
|
- curl 导出
|
|
|
|
### `GET /dev/config/local-files`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 列出本地配置目录中的 JSON 文件
|
|
|
|
### `POST /dev/events/{eventPublicID}/config-sources/import-local`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 从本地配置目录导入 source config
|
|
|
|
请求体重点：
|
|
|
|
- `fileName`
|
|
- `notes`
|
|
|
|
### `POST /dev/config-builds/preview`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 基于 source config 生成 preview build
|
|
|
|
请求体重点：
|
|
|
|
- `sourceId`
|
|
|
|
### `POST /dev/config-builds/publish`
|
|
|
|
环境：
|
|
|
|
- 仅 non-production
|
|
|
|
用途：
|
|
|
|
- 将成功的 preview build 发布成正式 release
|
|
- 自动切换 `event.current_release_id`
|
|
|
|
请求体重点：
|
|
|
|
- `buildId`
|
|
|
|
返回重点：
|
|
|
|
- `release.releaseId`
|
|
- `release.manifestUrl`
|
|
- `release.configLabel`
|