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

API 清单

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

POST /sessions/{sessionPublicID}/finish

鉴权：

• sessionToken

用途：

• 结束一局
• 同时沉淀结果摘要

请求体重点：

• 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