mini-prog/b2f.md

Backend To Frontend

这份文件只用于记录 backend 当前对 frontend 的联调要求和协作约束。

约定：

• 我只在这里写“后端已经具备什么、前端现在需要怎么接、哪些地方不能自行假设”
• 需要你拍板的事项，仍然先由你确认，不在这里直接定版
• 前端给 backend 的反馈不要写这里，另走 f2b.md

---

1. 当前联调基线

当前建议前端统一使用这组 demo 数据联调：

• eventPublicID = evt_demo_001
• channelCode = mini-demo
• channelType = wechat_mini

当前主链已经可联调：

• 微信小程序登录
• 首页聚合
• event play
• launch
• session start / finish
• session result

---

2. 当前已确认可用的后端能力

登录与用户：

• POST /auth/login/wechat-mini
• POST /auth/sms/send
• POST /auth/login/sms
• POST /auth/bind/mobile
• GET /me
• GET /me/profile

首页与入口：

• GET /entry/resolve
• GET /me/entry-home

活动与启动：

• GET /events/{eventPublicID}
• GET /events/{eventPublicID}/play
• POST /events/{eventPublicID}/launch

局内与结果：

• GET /sessions/{sessionPublicID}
• POST /sessions/{sessionPublicID}/start
• POST /sessions/{sessionPublicID}/finish
• GET /sessions/{sessionPublicID}/result
• GET /me/sessions
• GET /me/results

配置发布：

• GET /dev/config/local-files
• POST /dev/events/{eventPublicID}/config-sources/import-local
• POST /dev/config-builds/preview
• POST /dev/config-builds/publish

开发工具：

• POST /dev/bootstrap-demo
• GET /dev/workbench

---

3. 前端现在需要怎么接

3.1 登录

小程序当前主链：

1. POST /auth/login/wechat-mini
2. 保存 accessToken / refreshToken
3. 后续业务接口统一带 Bearer token

手机号绑定场景：

1. POST /auth/sms/send with scene=bind_mobile
2. POST /auth/bind/mobile

3.2 首页

首页直接接：

• GET /me/entry-home

不要自己拼：

• /me
• /home
• /cards
• /me/sessions

3.3 活动详情与开始前准备

活动详情 / 开始前准备页直接接：

• GET /events/{eventPublicID}/play

它的作用是：

• 判断当前是否可启动
• 判断主按钮应该是 start 还是 continue
• 返回当前会落到哪份 release

3.4 进入游戏

进入游戏必须走：

• POST /events/{eventPublicID}/launch

启动后前端应以这些字段为准：

• launch.resolvedRelease.releaseId
• launch.resolvedRelease.manifestUrl
• launch.resolvedRelease.manifestChecksumSha256
• launch.config.configUrl
• launch.config.configLabel
• launch.config.releaseId
• launch.config.routeCode
• launch.business.sessionId
• launch.business.sessionToken
• launch.business.sessionTokenExpiresAt

3.5 结果页

结果页直接接：

• GET /sessions/{sessionPublicID}/result

列表页直接接：

• GET /me/results

---

4. 前端必须遵守的约束

4.1 正式流程只认 launch 返回的 manifest

前端进入地图时：

• 不要自己拼 release URL
• 不要回退到本地样例配置路径
• 不要直接读取根目录 event/*.json

必须以 launch 返回的为准：

• manifestUrl
• manifestChecksumSha256
• releaseId

4.2 launch 返回契约先不要自行扩展假设

前端当前只消费已约定字段。

如果出现下面任一情况，直接反馈阻塞，不要自行猜：

• 字段缺失
• 字段改名
• 字段层级变化
• resolvedRelease 与 config 含义不一致

4.3 release manifest 再报错时必须带完整上下文

如果再出现配置加载失败，请回传：

• eventPublicID
• releaseId
• manifestUrl
• 页面报错文案
• 控制台日志
• 网络请求日志

---

5. 当前需要前端配合验证的事项

F-001 回归最新 demo release

当前建议回归使用：

• eventPublicID = evt_demo_001
• releaseId = rel_e7dd953743c5c0d2
• manifestUrl = https://oss-mbh5.colormaprun.com/gotomars/event/releases/evt_demo_001/rel_e7dd953743c5c0d2/manifest.json

需要前端验证：

1. play -> launch -> map load 已能走通
2. 地图页不再报 release manifest 不存在或未发布
3. 不再访问旧的失效 release

F-002 预埋“放弃恢复”调用位

这项先预埋，不要先自行定语义。

建议前端准备好：

• 在“放弃恢复”按钮点击后，预留调用 finish(cancelled) 的位置

但是否正式启用：

• 要等 backend 把 cancelled 语义确认完

F-003 首页 / play / result ongoing 语义联调

后面 backend 收稳 finished / failed / cancelled 之后，前端需要配合回归：

• /me/entry-home
• /events/{eventPublicID}/play
• /sessions/{sessionPublicID}/result

重点看：

• cancelled 后不再继续显示为 ongoing
• failed 后不再继续显示为 ongoing
• finished 后结果和首页摘要一致

---

6. 当前建议的前端接入顺序

1. 登录页
2. 首页
3. 活动详情页 / 开始前准备页
4. launch
5. session start / finish
6. 结果页
7. 我的页

---

7. 参考文档

• 后端总览 README
• 接口清单
• 开发说明
• 系统架构
• 核心流程