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

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