cmr-mini/backend/docs/接口清单.md

# API 清单
> 文档版本：v1.0
> 最后更新：2026-04-02


本文档只记录当前 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`