mini-prog/backend/docs/接口清单.md

API 清单

文档版本：v1.12 最后更新：2026-04-03 22:34:08

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

用途：

• 返回入口首页卡片
• 当前卡片摘要字段已统一补齐：
  • summary
  • status
  • statusCode
  • timeWindow
  • ctaText
  • isDefaultExperience
  • eventType
  • currentPresentation
  • currentContentBundle

GET /cards

用途：

• 只返回卡片列表
• 当前与 /home 使用同一套卡片摘要语义

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
• 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

当前 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

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 / 管理员权限模型

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

用途：

• 查看单个运行绑定详情

GET /home

用途：

• 返回入口首页摘要
• 当前卡片摘要字段已统一补齐：
  • summary
  • status
  • statusCode
  • timeWindow
  • ctaText
  • isDefaultExperience
  • eventType
  • currentPresentation
  • currentContentBundle

GET /cards

用途：

• 按入口返回活动卡片列表
• 当前与 /home 使用同一套卡片摘要语义

GET /me/entry-home

鉴权：

• Bearer token

用途：

• 返回“我的首页”聚合
• 当前 cards 也已统一使用活动卡片最小摘要字段