Add backend foundation and config-driven workbench

backend/docs/接口清单.md

@@ -0,0 +1,425 @@
+# 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`