# API 清单
> 文档版本：v1.8
> 最后更新：2026-04-03 12:36:15


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

`ongoingSession / recentSession` 当前会额外带：

- `variantId`
- `variantName`
- `routeCode`

## 4. Event

### `GET /events/{eventPublicID}`

用途：

- Event 详情

返回重点：

- `event`
- `release`
- `resolvedRelease`
- `runtime`
- `currentPresentation`
- `currentContentBundle`

当前摘要字段最少包括：

- `currentPresentation.presentationId`
- `currentPresentation.templateKey`
- `currentPresentation.version`
- `currentContentBundle.contentBundleId`
- `currentContentBundle.bundleType`
- `currentContentBundle.version`

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

鉴权：

- Bearer token

用途：

- 活动详情页 / 开始前准备页聚合

返回重点：

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

当前摘要字段最少包括：

- `currentPresentation.presentationId`
- `currentPresentation.templateKey`
- `currentPresentation.version`
- `currentContentBundle.contentBundleId`
- `currentContentBundle.bundleType`
- `currentContentBundle.version`

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

鉴权：

- Bearer token

用途：

- 基于当前 event 的可启动 release 创建一局 session

请求体重点：

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

补充说明：

- 如果当前 release 声明了 `play.courseVariants[]`
- `launch` 会返回最终绑定的 `launch.variant`
- 当前为兼容旧调用方，`assignmentMode=manual` 且未传 `variantId` 时，backend 会先回退到首个可选 variant

返回重点：

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

当前活动运营摘要最少包括：

- `launch.presentation.presentationId`
- `launch.presentation.templateKey`
- `launch.presentation.version`
- `launch.contentBundle.contentBundleId`
- `launch.contentBundle.bundleType`
- `launch.contentBundle.version`

`launch.runtime` 当前为兼容新增字段，最少会带：

- `runtimeBindingId`
- `placeId`
- `mapId`
- `tileReleaseId`
- `courseSetId`
- `courseVariantId`

如当前 release 尚未挂接 runtime binding，则该字段为空。

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

`session` 当前会额外带：

- `assignmentMode`
- `variantId`
- `variantName`
- `routeCode`

### `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`
- `variantId`
- `variantName`
- `routeCode`

### `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`
- `runtimeBindingId` 可选
- `presentationId` 可选
- `contentBundleId` 可选

返回重点：

- `release.releaseId`
- `release.manifestUrl`
- `release.configLabel`
- `runtime.runtimeBindingId` 可选

## 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}/presentations`

鉴权：

- Bearer token

用途：

- 查看某个 event 下的展示定义列表

### `POST /admin/events/{eventPublicID}/presentations`

鉴权：

- Bearer token

用途：

- 为 event 创建一条最小 presentation 定义

请求体重点：

- `code`
- `name`
- `presentationType`
- `schema`

### `POST /admin/events/{eventPublicID}/presentations/import`

鉴权：

- Bearer token

用途：

- 通过统一导入入口创建展示定义
- 第一阶段只记录：
  - `templateKey`
  - `sourceType`
  - `schemaUrl`
  - `version`
  - `title`

核心参数：

- `title`
- `templateKey`
- `sourceType`
- `schemaUrl`
- `version`

### `GET /admin/presentations/{presentationPublicID}`

鉴权：

- Bearer token

用途：

- 查看单条 presentation 明细

### `GET /admin/events/{eventPublicID}/content-bundles`

鉴权：

- Bearer token

用途：

- 查看某个 event 下的内容包列表

### `POST /admin/events/{eventPublicID}/content-bundles`

鉴权：

- Bearer token

用途：

- 为 event 创建一条最小 content bundle

请求体重点：

- `code`
- `name`
- `entryUrl`
- `assetRootUrl`
- `metadata`

### `POST /admin/events/{eventPublicID}/content-bundles/import`

鉴权：

- Bearer token

用途：

- 通过统一导入入口为 event 创建内容包
- 先记录 `bundleType / sourceType / manifestUrl / version / assetManifest`

请求体重点：

- `title`
- `bundleType`
- `sourceType`
- `manifestUrl`
- `version`
- `assetManifest`

### `GET /admin/content-bundles/{contentBundlePublicID}`

鉴权：

- Bearer token

用途：

- 查看单条 content bundle 明细

### `POST /admin/events/{eventPublicID}/defaults`

鉴权：

- Bearer token

用途：

- 固化 event 当前默认 active 绑定
- 后续 publish 在未显式传参时，优先继承：
  - `presentationId`
  - `contentBundleId`
  - `runtimeBindingId`

核心参数：

- `presentationId`
- `contentBundleId`
- `runtimeBindingId`

### `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
- 可选在发布时直接挂接：
  - `runtimeBindingId`
  - `presentationId`
  - `contentBundleId`
- 如果未显式传入 `runtimeBindingId / presentationId / contentBundleId`，会优先按 event 当前默认 active 绑定自动补齐

请求体重点：

- `runtimeBindingId` 可选
- `presentationId` 可选
- `contentBundleId` 可选

### `GET /admin/releases/{releasePublicID}`

鉴权：

- Bearer token

用途：

- 查看单个 release 明细
- 带出当前已挂接的最小 runtime / presentation / content bundle 摘要

当前 release 摘要最少包括：

- `presentation.presentationId`
- `presentation.templateKey`
- `presentation.version`
- `contentBundle.contentBundleId`
- `contentBundle.bundleType`
- `contentBundle.version`
- `runtime.runtimeBindingId`
- `runtime.placeId`
- `runtime.mapId`
- `runtime.tileReleaseId`
- `runtime.courseVariantId`

### `POST /admin/releases/{releasePublicID}/runtime-binding`

鉴权：

- Bearer token

用途：

- 将某个 `runtimeBindingId` 挂接到指定 release
- 为后续 `launch.runtime` 提供运行对象来源

请求体重点：

- `runtimeBindingId`

### `POST /admin/events/{eventPublicID}/rollback`

鉴权：

- Bearer token

用途：

- 将 event 当前 release 显式切回某个已发布 release

请求体重点：

- `releaseId`

## 10. Admin 生产骨架

说明：

- 当前是总控确认后的第一阶段生产骨架接口
- 重点先覆盖：
  - `Place`
  - `MapAsset`
  - `TileRelease`
  - `CourseSource`
  - `CourseSet`
  - `CourseVariant`
  - `MapRuntimeBinding`
- 这批接口不会替换现有 `events / event_releases / launch` 主链，而是增量补运行域对象

### `GET /admin/places`

鉴权：

- Bearer token

用途：

- 获取地点对象列表

### `POST /admin/places`

鉴权：

- Bearer token

用途：

- 新建地点对象

请求体重点：

- `code`
- `name`
- `region`
- `coverUrl`
- `description`
- `centerPoint`
- `status`

### `GET /admin/places/{placePublicID}`

鉴权：

- Bearer token

用途：

- 查看地点详情
- 同时带出该地点下的地图资产列表

### `POST /admin/places/{placePublicID}/map-assets`

鉴权：

- Bearer token

用途：

- 在某个地点下创建地图资产

请求体重点：

- `code`
- `name`
- `mapType`
- `legacyMapId`
- `coverUrl`
- `description`
- `status`

### `GET /admin/map-assets/{mapAssetPublicID}`

鉴权：

- Bearer token

用途：

- 查看地图资产详情
- 同时带出瓦片版本和赛道集合摘要

### `POST /admin/map-assets/{mapAssetPublicID}/tile-releases`

鉴权：

- Bearer token

用途：

- 为某个地图资产创建瓦片版本

请求体重点：

- `legacyVersionId`
- `versionCode`
- `tileBaseUrl`
- `metaUrl`
- `publishedAssetRoot`
- `metadata`
- `status`
- `setAsCurrent`

### `GET /admin/course-sources`

鉴权：

- Bearer token

用途：

- 获取赛道原始输入源列表

### `POST /admin/course-sources`

鉴权：

- Bearer token

用途：

- 新建赛道原始输入源
- 用于承接 KML / GeoJSON 等输入

请求体重点：

- `legacyPlayfieldId`
- `legacyVersionId`
- `sourceType`
- `fileUrl`
- `checksum`
- `parserVersion`
- `importStatus`
- `metadata`

### `GET /admin/course-sources/{sourcePublicID}`

鉴权：

- Bearer token

用途：

- 查看单个赛道输入源详情

### `POST /admin/map-assets/{mapAssetPublicID}/course-sets`

鉴权：

- Bearer token

用途：

- 在某个地图资产下创建赛道集合

请求体重点：

- `code`
- `mode`
- `name`
- `description`
- `status`

### `GET /admin/course-sets/{courseSetPublicID}`

鉴权：

- Bearer token

用途：

- 查看赛道集合详情
- 同时带出它的 variant 列表

### `POST /admin/course-sets/{courseSetPublicID}/variants`

鉴权：

- Bearer token

用途：

- 为某个赛道集合创建具体可运行赛道方案

请求体重点：

- `sourceId`
- `name`
- `routeCode`
- `mode`
- `controlCount`
- `difficulty`
- `configPatch`
- `metadata`
- `status`
- `isDefault`

### `GET /admin/runtime-bindings`

鉴权：

- Bearer token

用途：

- 获取活动运行绑定列表

### `POST /admin/runtime-bindings`

鉴权：

- Bearer token

用途：

- 把活动和地点、地图资产、瓦片版本、赛道方案正式绑定起来

请求体重点：

- `eventId`
- `placeId`
- `mapAssetId`
- `tileReleaseId`
- `courseSetId`
- `courseVariantId`
- `status`
- `notes`

### `GET /admin/runtime-bindings/{runtimeBindingPublicID}`

鉴权：

- Bearer token

用途：

- 查看单个运行绑定详情


