zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6964e26ec9be8f593b31719f76443905df56bae8
cmr-mini/backend/docs/接口清单.md

775 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API 清单
> 文档版本：v1.0
> 最后更新：2026-04-02 09:01:17
本文档只记录当前 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`
补充约束：
- 幂等
- 重复调用时：
- `launched` 会推进到 `running`
- `running` 或已终态直接返回当前 session
### `POST /sessions/{sessionPublicID}/finish`
鉴权：
- `sessionToken`
用途：
- 结束一局
- 同时沉淀结果摘要
当前结束语义：
- `finished`：正常完成
- `failed`：超时或规则失败
- `cancelled`：主动退出或放弃恢复
补充约束：
- 幂等
- 已终态重复调用直接返回当前 session / result
- `finish(cancelled)` 是当前“放弃恢复”的官方后端语义
- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
请求体重点：
- `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`
## 9. Admin 资源对象
说明：
- 当前是后台第一版的最小对象接口
- 先只做 Bearer 鉴权
- 暂未接正式 RBAC / 管理员权限模型
### `GET /admin/maps`
鉴权：
- Bearer token
用途：
- 获取地图对象列表
### `POST /admin/maps`
鉴权：
- Bearer token
用途：
- 新建地图对象
请求体重点：
- `code`
- `name`
- `status`
- `description`
### `GET /admin/maps/{mapPublicID}`
鉴权：
- Bearer token
用途：
- 获取地图对象详情和版本列表
### `POST /admin/maps/{mapPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建地图版本
请求体重点：
- `versionCode`
- `mapmetaUrl`
- `tilesRootUrl`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`
### `GET /admin/playfields`
鉴权：
- Bearer token
用途：
- 获取赛场 / KML 对象列表
### `POST /admin/playfields`
鉴权：
- Bearer token
用途：
- 新建赛场对象
请求体重点：
- `code`
- `name`
- `kind`
- `status`
- `description`
### `GET /admin/playfields/{playfieldPublicID}`
鉴权：
- Bearer token
用途：
- 获取赛场对象详情和版本列表
### `POST /admin/playfields/{playfieldPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建赛场版本
请求体重点：
- `versionCode`
- `sourceType`
- `sourceUrl`
- `controlCount`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`
### `GET /admin/resource-packs`
鉴权：
- Bearer token
用途：
- 获取资源包对象列表
### `POST /admin/resource-packs`
鉴权：
- Bearer token
用途：
- 新建资源包对象
请求体重点：
- `code`
- `name`
- `status`
- `description`
### `GET /admin/resource-packs/{resourcePackPublicID}`
鉴权：
- Bearer token
用途：
- 获取资源包对象详情和版本列表
### `POST /admin/resource-packs/{resourcePackPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建资源包版本
请求体重点：
- `versionCode`
- `contentEntryUrl`
- `audioRootUrl`
- `themeProfileCode`
- `status`
- `publishedAssetRoot`
- `metadata`
- `setAsCurrent`
### `GET /admin/events`
鉴权：
- Bearer token
用途：
- 获取后台 Event 列表
### `POST /admin/events`
鉴权：
- Bearer token
用途：
- 新建后台 Event
请求体重点：
- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`
### `GET /admin/events/{eventPublicID}`
鉴权：
- Bearer token
用途：
- 获取后台 Event 详情
- 返回最新 source config 摘要
### `PUT /admin/events/{eventPublicID}`
鉴权：
- Bearer token
用途：
- 更新 Event 基础信息
请求体重点：
- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`
### `POST /admin/events/{eventPublicID}/source`
鉴权：
- Bearer token
用途：
- 用地图版本、赛场版本、资源包版本组装一版 source config
- 直接落到现有 `event_config_sources`
请求体重点：
- `map.mapId`
- `map.versionId`
- `playfield.playfieldId`
- `playfield.versionId`
- `resourcePack.resourcePackId`
- `resourcePack.versionId`
- `gameModeCode`
- `routeCode`
- `overrides`
- `notes`
### `GET /admin/events/{eventPublicID}/pipeline`
鉴权：
- Bearer token
用途：
- 从后台视角聚合查看某个 event 的：
- sources
- builds
- releases
- current release
### `POST /admin/sources/{sourceID}/build`
鉴权：
- Bearer token
用途：
- 基于某个 source 生成 preview build
### `GET /admin/builds/{buildID}`
鉴权：
- Bearer token
用途：
- 查看某次 build 详情
### `POST /admin/builds/{buildID}/publish`
鉴权：
- Bearer token
用途：
- 将某次成功 build 发布成正式 release
- 自动切换 event 当前 release
### `POST /admin/events/{eventPublicID}/rollback`
鉴权：
- Bearer token
用途：
- 将 event 当前 release 显式切回某个已发布 release
请求体重点：
- `releaseId`
Reference in New Issue View Git Blame Copy Permalink