# API 清单 > 文档版本：v1.23 > 最后更新：2026-04-07 16:08:37 本文档只记录当前 backend 已实现接口，不写未来规划接口。 当前已实现接口总数： - `115` ## 1. Health ### `GET /healthz` 用途： - 健康检查 ## 0. Workbench ### `GET /dev/workbench` 用途： - 调试工作台 - 一键回归、日志查看、摘要排查 ### `GET /admin/ops-workbench` 用途： - 运维后台第一期页面 - 资源录入、OSS 纳管、地图瓦片导入、KML 批量导入 ## 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 ## 2.1 Ops Auth 说明： - 运维账号与前端玩家账号完全分离 - 生产环境走手机号验证码运维账号 - 开发环境为了录资源和调发布方便，`/admin/ops-workbench` 与 `/ops/admin/*` 默认免登录可用 ### `POST /ops/auth/sms/send` 用途： - 发送运维账号登录 / 注册验证码 ### `POST /ops/auth/register` 用途： - 注册独立运维账号 - 首个账号默认授予 `owner` ### `POST /ops/auth/login/sms` 用途： - 运维账号手机号验证码登录 ### `POST /ops/auth/refresh` 用途： - 刷新运维 access token ### `POST /ops/auth/logout` 用途： - 撤销运维 refresh token ### `GET /ops/me` 鉴权： - Ops bearer token 用途： - 获取当前运维账号信息和主角色 ## 2.2 Ops Admin（地图资源管理第一刀） ### `GET /ops/admin/summary` 用途： - 运维后台总览聚合接口 - 返回资源、活动、运行绑定、发布版本统计 ### `GET /ops/admin/assets` 用途： - 读取受管资源列表 - 给运维后台资源总览与录入校验使用 ### `POST /ops/admin/assets/register-link` 用途： - 登记已有正式外链资源 - 统一纳管到 backend 资源对象 ### `POST /ops/admin/assets/upload` 用途： - 上传文件给 backend，再统一存入 OSS - 运维不需要自己处理底层存储细节 ### `GET /ops/admin/assets/{assetPublicID}` 用途： - 查看单个受管资源详情 - 返回资源类型、版本、正式 URL 和元数据 ### `GET /ops/admin/places` 用途： - 读取地点列表 - 给运维后台地图资源管理区做浏览入口 ### `POST /ops/admin/places` 用途： - 新建地点 ### `GET /ops/admin/places/{placePublicID}` 用途： - 读取地点详情 - 返回当前地点下的地图资源列表 ### `POST /ops/admin/places/{placePublicID}/map-assets` 用途： - 在指定地点下新建地图资源 ### `GET /ops/admin/map-assets/{mapAssetPublicID}` 用途： - 读取地图资源详情 - 返回当前瓦片版本、关联赛道集和关联活动摘要 ### `GET /ops/admin/map-assets` 用途： - 读取地图列表 - 返回地点、当前瓦片版本和关联活动摘要 ### `PUT /ops/admin/map-assets/{mapAssetPublicID}` 用途： - 更新地图基础信息 - 支持名称、封面、摘要、状态维护 ### `POST /ops/admin/map-assets/{mapAssetPublicID}/tile-releases` 用途： - 给地图资源追加新的瓦片版本 ### `POST /ops/admin/ops/tile-releases/import` 用途： - 一次录入 `place + map asset + tile release` - 运维录入地图瓦片版本的最小入口 ### `GET /ops/admin/course-sources` 用途： - 运维后台读取 KML / GeoJSON 输入源列表 ### `GET /ops/admin/course-sources/{sourcePublicID}` 用途： - 运维后台读取单个赛道输入源详情 ### `GET /ops/admin/course-sets/{courseSetPublicID}` 用途： - 运维后台读取赛道集合详情 - 用于默认路线和路线预览 ### `POST /ops/admin/ops/course-sets/import-kml-batch` 用途： - 批量录入一组 KML - 自动生成 `course set + variants` ### `GET /ops/admin/events` 用途： - 运维后台活动列表 - 给地图关联活动区做浏览入口 ### `POST /ops/admin/events` 用途： - 运维后台新建活动 - 先录活动基础信息，再进入默认绑定和发布链 ### `GET /ops/admin/events/{eventPublicID}` 用途： - 运维后台活动详情 - 返回默认绑定和当前 source 摘要 ### `PUT /ops/admin/events/{eventPublicID}` 用途： - 运维后台更新活动基础信息 - 支持名称、摘要、slug、状态维护 ### `POST /ops/admin/events/{eventPublicID}/presentations/import` 用途： - 导入活动展示定义 - 用于当前活动默认绑定与发布 ### `POST /ops/admin/events/{eventPublicID}/content-bundles/import` 用途： - 导入活动内容包 - 用于当前活动默认绑定与发布 ### `POST /ops/admin/events/{eventPublicID}/defaults` 用途： - 保存活动默认绑定 - 固化 `runtime / presentation / content bundle` 三元组 ### `GET /ops/admin/events/{eventPublicID}/pipeline` 用途： - 读取活动发布链概览 - 返回 source / build / release 摘要 ### `POST /ops/admin/sources/{sourceID}/build` 用途： - 基于 source 构建 build ### `GET /ops/admin/builds/{buildID}` 用途： - 读取单个 build 明细 ### `POST /ops/admin/builds/{buildID}/publish` 用途： - 发布 build 为正式 release ### `GET /ops/admin/releases/{releasePublicID}` 用途： - 读取单个 release 详情 ### `POST /ops/admin/events/{eventPublicID}/rollback` 用途： - 将活动当前 release 回滚到指定版本 ## 3. Entry / Home ### `GET /entry/resolve` 用途： - 解析当前入口归属哪个 tenant / channel 查询参数： - `channelCode` - `channelType` - `platformAppId` ## 3.1 Public Experience ### `GET /public/experience-maps` 用途： - 游客模式地图列表 - 返回可公开体验的地图与默认活动摘要 ### `GET /public/experience-maps/{mapAssetPublicID}` 用途： - 游客模式地图详情 - 返回某张地图下挂载的默认体验活动 ### `GET /public/events/{eventPublicID}` 用途： - 游客模式活动详情 - 只允许默认体验活动 ### `GET /public/events/{eventPublicID}/play` 用途： - 游客模式准备页聚合接口 - 返回 `canLaunch`、`assignmentMode`、`courseVariants`、`preview` ### `POST /public/events/{eventPublicID}/launch` 用途： - 游客模式启动一局 - 返回与正式 launch 近似结构，并带 `business.isGuest = true` 核心参数： - `releaseId` - `variantId` - `clientType` - `deviceKey` - `tenantCode` ### `GET /home` 用途： - 返回入口首页卡片 - 当前卡片摘要字段已统一补齐： - `summary` - `status` - `statusCode` - `timeWindow` - `ctaText` - `isDefaultExperience` - `eventType` - `currentPresentation` - `currentContentBundle` ### `GET /cards` 用途： - 只返回卡片列表 - 当前与 `/home` 使用同一套卡片摘要语义 当前额外补充： - `showInEventList` ### `GET /experience-maps` 用途： - 地图资源列表 - 返回每张地图下默认体验活动数量和默认活动 ID 列表 返回重点： - `placeId` - `placeName` - `mapId` - `mapName` - `coverUrl` - `summary` - `defaultExperienceCount` - `defaultExperienceEventIds` ### `GET /experience-maps/{mapAssetPublicID}` 用途： - 地图详情 - 返回地图基础信息和默认体验活动摘要 返回重点： - `tileBaseUrl` - `tileMetaUrl` - `defaultExperiences[]` `defaultExperiences[]` 当前包含： - `eventId` - `title` - `subtitle` - `eventType` - `status` - `statusCode` - `ctaText` - `isDefaultExperience` - `showInEventList` - `currentPresentation` - `currentContentBundle` ### `GET /me/entry-home` 鉴权： - Bearer token 用途： - 首页聚合接口 - 当前 `cards` 也已统一使用活动卡片最小摘要字段 返回重点： - `user` - `tenant` - `channel` - `cards` - `ongoingSession` - `recentSession` `ongoingSession / recentSession` 当前会额外带： - `variantId` - `variantName` - `routeCode` ## 4. Event ### `GET /events/{eventPublicID}` 用途： - Event 详情 返回重点： - `event` - `release` - `resolvedRelease` - `runtime` - `preview` - `currentPresentation` - `currentContentBundle` 当前摘要字段最少包括： - `currentPresentation.presentationId` - `currentPresentation.templateKey` - `currentPresentation.version` - `currentContentBundle.contentBundleId` - `currentContentBundle.bundleType` - `currentContentBundle.version` 当前 `preview` 为准备页地图预览 V1 只读增强字段，最小包括： - `preview.mode` - `preview.baseTiles.tileBaseUrl` - `preview.baseTiles.zoom` - `preview.baseTiles.tileSize` - `preview.viewport.width / height` - `preview.viewport.minLon / minLat / maxLon / maxLat` - `preview.variants[].controls` - `preview.variants[].legs` - `preview.selectedVariantId` ### `GET /events/{eventPublicID}/play` 鉴权： - Bearer token 用途： - 活动详情页 / 开始前准备页聚合 返回重点： - `event` - `release` - `resolvedRelease` - `runtime` - `preview` - `currentPresentation` - `currentContentBundle` - `play.assignmentMode` - `play.courseVariants` - `play.canLaunch` - `play.primaryAction` - `play.launchSource` - `play.ongoingSession` - `play.recentSession` 当前 `play.canLaunch=true` 的最小前置条件为： - event `status = active` - 当前已发布 release 存在 - 当前已发布 release 有 `manifest` - 当前已发布 release 已绑定 `runtime` - 当前已发布 release 已绑定 `presentation` - 当前已发布 release 已绑定 `content bundle` 当前摘要字段最少包括： - `currentPresentation.presentationId` - `currentPresentation.templateKey` - `currentPresentation.version` - `currentContentBundle.contentBundleId` - `currentContentBundle.bundleType` - `currentContentBundle.version` 当前 `preview` 继续表示准备页地图预览 V1 只读增强字段，结构与 `GET /events/{eventPublicID}` 相同。 ### `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` 与 `play.canLaunch` 使用同一套前置条件 - 若当前发布 release 缺少： - `runtime` - `presentation` - `content bundle` 之一，`launch` 会直接返回 `409` 返回重点： - `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` ### `GET /dev/demo-assets/presentations/{demoKey}` 环境： - 仅 non-production 用途： - 返回联调用的示例展示定义 schema - 给 workbench 的玩法切换自动填充真实 `presentation schema` 资源地址 路径参数： - `demoKey` - 当前支持：`classic`、`score-o`、`manual-variant` ### `GET /dev/demo-assets/content-manifests/{demoKey}` 环境： - 仅 non-production 用途： - 返回联调用的示例内容 manifest - 给 workbench 的玩法切换自动填充真实 `content manifest` 资源地址 路径参数： - `demoKey` - 当前支持：`classic`、`score-o`、`manual-variant` 补充说明： - 只用于 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 / 管理员权限模型 - 运维后台当前已开始切到独立前缀： - `/ops/admin/*` - 这批接口在运维后台中与 `/admin/*` 使用同一套 handler，语义一致 ### `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 用途： - 查看地图资产详情 - 同时带出瓦片版本和赛道集合摘要 ### `GET /admin/map-assets` 鉴权： - Bearer token 用途： - 查看地图资产列表 - 返回地点、当前瓦片版本和关联活动摘要 ### `PUT /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 用途： - 查看单个运行绑定详情 ### `POST /admin/ops/tile-releases/import` 鉴权： - Bearer token 用途： - 运维入口第一期：按 `place + map asset + tile release` 一次录入瓦片版本 - 可在录入时直接指定 `setAsCurrent` 请求体重点： - `placeCode` - `placeName` - `mapAssetCode` - `mapAssetName` - `mapType` - `versionCode` - `tileBaseUrl` - `metaUrl` - `publishedAssetRoot` - `setAsCurrent` ### `POST /admin/ops/course-sets/import-kml-batch` 鉴权： - Bearer token 用途： - 运维入口第一期：按一组 KML 路线批量录入赛道集合与 variants - 适合把同一场地的一批路线一次性整理成 `course set` 请求体重点： - `placeCode` - `placeName` - `mapAssetCode` - `mapAssetName` - `mapType` - `courseSetCode` - `courseSetName` - `mode` - `defaultRouteCode` - `routes[]` ### `GET /admin/assets` 鉴权： - Bearer token 用途： - 查看当前 backend 已纳管的正式资源对象列表 ### `POST /admin/assets/register-link` 鉴权： - Bearer token 用途： - 登记一个已有正式外链为受管资源 请求体重点： - `assetType` - `assetCode` - `version` - `publicUrl` - `status` - `metadata` ### `POST /admin/assets/upload` 鉴权： - Bearer token 用途： - 通过 backend 上传一个正式资源文件到 OSS，并自动纳管 表单重点： - `assetType` - `assetCode` - `version` - `title` - `objectDir` 可选 - `status` - `metadataJson` 可选 - `file` ### `GET /admin/assets/{assetPublicID}` 鉴权： - Bearer token 用途： - 查看单个已纳管资源对象详情 ### `GET /home` 用途： - 返回入口首页摘要 - 当前卡片摘要字段已统一补齐： - `summary` - `status` - `statusCode` - `timeWindow` - `ctaText` - `isDefaultExperience` - `eventType` - `currentPresentation` - `currentContentBundle` ### `GET /cards` 用途： - 按入口返回活动卡片列表 - 当前与 `/home` 使用同一套卡片摘要语义 ### `GET /me/entry-home` 鉴权： - Bearer token 用途： - 返回“我的首页”聚合 - 当前 `cards` 也已统一使用活动卡片最小摘要字段