zhangyan/cmr-mini

Fork 0

Files

zhangyan a70dc8d5d0 完善后端联调链路与模拟器多通道支持

2026-04-01 18:48:59 +08:00

5.3 KiB

Raw Blame History

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 登录

小程序当前主链：

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

手机号绑定场景：

POST /auth/sms/send with scene=bind_mobile
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

需要前端验证：

play -> launch -> map load 已能走通
地图页不再报 release manifest 不存在或未发布
不再访问旧的失效 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. 当前建议的前端接入顺序

登录页
首页
活动详情页 / 开始前准备页
launch
session start / finish
结果页
我的页

5.3 KiB Raw Blame History