zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

整理前后端联调协作文档

Browse Source
This commit is contained in:
zhangyan
2026-04-01 19:05:28 +08:00
parent f7393907ec
commit 0490b8605c
3 changed files with 347 additions and 412 deletions
Download Patch File Download Diff File Expand all files Collapse all files

346
b2f.md
View File

@@ -1,250 +1,162 @@
# Backend To Frontend
# b2f
这份文件只用于记录 backend 当前对 frontend 的联调要求和协作约束。
说明：
约定：
- 我只在这里写“后端已经具备什么、前端现在需要怎么接、哪些地方不能自行假设”
- 需要你拍板的事项，仍然先由你确认，不在这里直接定版
- 前端给 backend 的反馈不要写这里，另走 `f2b.md`
- 只写事实和请求
- 每条固定包含：时间、谁提的、当前事实、需要对方确认什么、是否已解决
---
## 1. 当前联调基线
## 待确认
当前建议前端统一使用这组 demo 数据联调：
### B2F-001
- `eventPublicID = evt_demo_001`
- `channelCode = mini-demo`
- `channelType = wechat_mini`
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- backend 当前主链已经可联调：
- `POST /auth/login/wechat-mini`
- `GET /me/entry-home`
- `GET /events/{eventPublicID}/play`
- `POST /events/{eventPublicID}/launch`
- `POST /sessions/{sessionPublicID}/start`
- `POST /sessions/{sessionPublicID}/finish`
- `GET /sessions/{sessionPublicID}/result`
- 当前建议统一使用 demo 入口：
- `eventPublicID = evt_demo_001`
- `channelCode = mini-demo`
- `channelType = wechat_mini`
- 需要对方确认什么：
- frontend 是否按这组 demo 数据作为当前唯一联调入口
- 是否已解决：否
当前主链已经可联调：
### B2F-002
- 微信小程序登录
- 首页聚合
- `event play`
- `launch`
- `session start / finish`
- `session result`
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- 进入游戏的正式流程必须以 `launch` 返回值为准
- backend 当前约定字段：
- `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`
- 需要对方确认什么：
- frontend 是否确认正式流程只消费上述字段，不再自行推断 release URL
- 是否已解决：否
### B2F-003
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- backend 准备把“放弃恢复”收口为 `finish(cancelled)` 语义
- 当前语义尚未最终拍板
- 需要对方确认什么：
- frontend 是否可以先预埋“放弃恢复”调用位，但在语义确认前不默认启用
- 是否已解决：否
---
## 2. 当前已确认可用的后端能力
## 已确认
登录与用户：
### B2F-004
- `POST /auth/login/wechat-mini`
- `POST /auth/sms/send`
- `POST /auth/login/sms`
- `POST /auth/bind/mobile`
- `GET /me`
- `GET /me/profile`
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- 正式联调时不应回退到本地样例配置路径
- 不应直接读取根目录 `event/*.json`
- 应只认 launch 返回的 `manifestUrl`
- 需要对方确认什么：
- 无
- 是否已解决：是
首页与入口：
### B2F-005
- `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`
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- 接口说明优先看 workbench 里的中文 API 列表
- 深入字段说明再看 [接口清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
- 需要对方确认什么：
- 无
- 是否已解决：是
---
## 3. 前端现在需要怎么接
## 阻塞
## 3.1 登录
### B2F-006
小程序当前主链：
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`
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- 如果 frontend 再出现 manifest 加载失败，backend 仅靠一句“加载失败”无法定位
- 需要对方确认什么：
- 如再出现此类问题，请一次性提供：
- `eventPublicID`
- `releaseId`
- `manifestUrl`
- 页面报错文案
- 控制台日志
- 网络请求日志
- 是否已解决：否
---
## 4. 前端必须遵守的约束
## 已完成
## 4.1 正式流程只认 launch 返回的 manifest
### B2F-007
前端进入地图时：
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- backend 已修复 `publish build` 只写 DB、不上传 OSS 的问题
- 新发布的 demo release manifest 已可正常访问
- 当前可用 release：
- `eventPublicID = evt_demo_001`
- `releaseId = rel_e7dd953743c5c0d2`
- `manifestUrl = https://oss-mbh5.colormaprun.com/gotomars/event/releases/evt_demo_001/rel_e7dd953743c5c0d2/manifest.json`
- 需要对方确认什么：
- 无
- 是否已解决：是
- 不要自己拼 release URL
- 不要回退到本地样例配置路径
- 不要直接读取根目录 `event/*.json`
### B2F-008
必须以 launch 返回的为准：
- `manifestUrl`
- `manifestChecksumSha256`
- `releaseId`
## 4.2 launch 返回契约先不要自行扩展假设
前端当前只消费已约定字段。
如果出现下面任一情况，直接反馈阻塞，不要自行猜：
- 字段缺失
- 字段改名
- 字段层级变化
- `resolvedRelease` 与 `config` 含义不一致
## 4.3 release manifest 再报错时必须带完整上下文
如果再出现配置加载失败，请回传：
- `eventPublicID`
- `releaseId`
- `manifestUrl`
- 页面报错文案
- 控制台日志
- 网络请求日志
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- backend workbench 已支持中文 API 列表
- 当前可用于日常联调：
- `POST /dev/bootstrap-demo`
- `GET /dev/workbench`
- 需要对方确认什么：
- 无
- 是否已解决：是
---
## 5. 当前需要前端配合验证的事项
## 下一步
## F-001 回归最新 demo release
### B2F-009
当前建议回归使用：
- `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](D:/dev/cmr-mini/backend/README.md)
- [接口清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
- [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)
- [系统架构](D:/dev/cmr-mini/backend/docs/系统架构.md)
- [核心流程](D:/dev/cmr-mini/backend/docs/核心流程.md)
- 时间：2026-04-01
- 谁提的：backend
- 当前事实：
- backend 下一步会优先处理 P0：
- 固定 `finished / failed / cancelled`
- 明确“放弃恢复”是否落 `cancelled`
- 收稳 `start / finish` 幂等
- 需要对方确认什么：
- frontend 当前优先配合：
- 用最新 demo release 回归 `play -> launch -> map load`
- 确认正式流程只认 launch 返回的 `manifestUrl`
- 预埋“放弃恢复”调用位
- 是否已解决：否