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