# API 清单 > 文档版本：v1.9 > 最后更新：2026-04-03 16:16:38 本文档只记录当前 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 ### `POST /dev/client-logs` 环境： - 仅 non-production 用途： - 接收 frontend 主动上报的调试日志 - 供 backend 通过 workbench 统一查看和排查 请求体重点： - `source` - `level` - `category` - `message` - `eventId` - `releaseId` - `sessionId` - `manifestUrl` - `route` - `occurredAt` - `details` 补充说明： - 当前只保存在内存中 - 默认最多保留最近 200 条 - 仅用于联调调试 ### `GET /dev/client-logs` 环境： - 仅 non-production 用途： - 获取 frontend 最近上报的调试日志 查询参数： - `limit` ### `DELETE /dev/client-logs` 环境： - 仅 non-production 用途： - 清空当前内存中的 frontend 调试日志 ### `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 导出 - frontend 调试日志查看/清空 ### `GET /dev/manifest-summary` 环境： - 仅 non-production 用途： - 由 backend 代读指定 manifest - 返回最小调试摘要： - `schemaVersion` - `playfield.kind` - `game.mode` 补充说明： - 只用于 workbench 联调排查 - 不参与正式客户端运行链路 ### `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 用途： - 查看单个运行绑定详情