整理前后端联调协作文档
This commit is contained in:
292
b2f.md
292
b2f.md
@@ -1,127 +1,42 @@
|
||||
# Backend To Frontend
|
||||
# b2f
|
||||
|
||||
这份文件只用于记录 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. 当前已确认可用的后端能力
|
||||
|
||||
登录与用户：
|
||||
### B2F-001
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- backend 当前主链已经可联调：
|
||||
- `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`
|
||||
- 当前建议统一使用 demo 入口：
|
||||
- `eventPublicID = evt_demo_001`
|
||||
- `channelCode = mini-demo`
|
||||
- `channelType = wechat_mini`
|
||||
- 需要对方确认什么：
|
||||
- frontend 是否按这组 demo 数据作为当前唯一联调入口
|
||||
- 是否已解决：否
|
||||
|
||||
配置发布：
|
||||
|
||||
- `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`
|
||||
|
||||
启动后前端应以这些字段为准：
|
||||
### B2F-002
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- 进入游戏的正式流程必须以 `launch` 返回值为准
|
||||
- backend 当前约定字段：
|
||||
- `launch.resolvedRelease.releaseId`
|
||||
- `launch.resolvedRelease.manifestUrl`
|
||||
- `launch.resolvedRelease.manifestChecksumSha256`
|
||||
@@ -132,119 +47,116 @@
|
||||
- `launch.business.sessionId`
|
||||
- `launch.business.sessionToken`
|
||||
- `launch.business.sessionTokenExpiresAt`
|
||||
- 需要对方确认什么：
|
||||
- frontend 是否确认正式流程只消费上述字段，不再自行推断 release URL
|
||||
- 是否已解决：否
|
||||
|
||||
## 3.5 结果页
|
||||
### B2F-003
|
||||
|
||||
结果页直接接：
|
||||
|
||||
- `GET /sessions/{sessionPublicID}/result`
|
||||
|
||||
列表页直接接：
|
||||
|
||||
- `GET /me/results`
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- backend 准备把“放弃恢复”收口为 `finish(cancelled)` 语义
|
||||
- 当前语义尚未最终拍板
|
||||
- 需要对方确认什么：
|
||||
- frontend 是否可以先预埋“放弃恢复”调用位，但在语义确认前不默认启用
|
||||
- 是否已解决：否
|
||||
|
||||
---
|
||||
|
||||
## 4. 前端必须遵守的约束
|
||||
## 已确认
|
||||
|
||||
## 4.1 正式流程只认 launch 返回的 manifest
|
||||
### B2F-004
|
||||
|
||||
前端进入地图时：
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- 正式联调时不应回退到本地样例配置路径
|
||||
- 不应直接读取根目录 `event/*.json`
|
||||
- 应只认 launch 返回的 `manifestUrl`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 是否已解决：是
|
||||
|
||||
- 不要自己拼 release URL
|
||||
- 不要回退到本地样例配置路径
|
||||
- 不要直接读取根目录 `event/*.json`
|
||||
### B2F-005
|
||||
|
||||
必须以 launch 返回的为准：
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- 接口说明优先看 workbench 里的中文 API 列表
|
||||
- 深入字段说明再看 [接口清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 是否已解决：是
|
||||
|
||||
- `manifestUrl`
|
||||
- `manifestChecksumSha256`
|
||||
- `releaseId`
|
||||
---
|
||||
|
||||
## 4.2 launch 返回契约先不要自行扩展假设
|
||||
## 阻塞
|
||||
|
||||
前端当前只消费已约定字段。
|
||||
|
||||
如果出现下面任一情况，直接反馈阻塞，不要自行猜：
|
||||
|
||||
- 字段缺失
|
||||
- 字段改名
|
||||
- 字段层级变化
|
||||
- `resolvedRelease` 与 `config` 含义不一致
|
||||
|
||||
## 4.3 release manifest 再报错时必须带完整上下文
|
||||
|
||||
如果再出现配置加载失败，请回传：
|
||||
### B2F-006
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- 如果 frontend 再出现 manifest 加载失败，backend 仅靠一句“加载失败”无法定位
|
||||
- 需要对方确认什么：
|
||||
- 如再出现此类问题，请一次性提供：
|
||||
- `eventPublicID`
|
||||
- `releaseId`
|
||||
- `manifestUrl`
|
||||
- 页面报错文案
|
||||
- 控制台日志
|
||||
- 网络请求日志
|
||||
- 是否已解决：否
|
||||
|
||||
---
|
||||
|
||||
## 5. 当前需要前端配合验证的事项
|
||||
## 已完成
|
||||
|
||||
## F-001 回归最新 demo release
|
||||
|
||||
当前建议回归使用：
|
||||
### 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`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 是否已解决：是
|
||||
|
||||
需要前端验证：
|
||||
### B2F-008
|
||||
|
||||
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` 后结果和首页摘要一致
|
||||
- 时间：2026-04-01
|
||||
- 谁提的：backend
|
||||
- 当前事实：
|
||||
- backend workbench 已支持中文 API 列表
|
||||
- 当前可用于日常联调：
|
||||
- `POST /dev/bootstrap-demo`
|
||||
- `GET /dev/workbench`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 是否已解决：是
|
||||
|
||||
---
|
||||
|
||||
## 6. 当前建议的前端接入顺序
|
||||
## 下一步
|
||||
|
||||
1. 登录页
|
||||
2. 首页
|
||||
3. 活动详情页 / 开始前准备页
|
||||
4. launch
|
||||
5. session start / finish
|
||||
6. 结果页
|
||||
7. 我的页
|
||||
### B2F-009
|
||||
|
||||
---
|
||||
|
||||
## 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`
|
||||
- 预埋“放弃恢复”调用位
|
||||
- 是否已解决：否
|
||||
|
||||
@@ -60,6 +60,32 @@
|
||||
|
||||
---
|
||||
|
||||
## 2.3 当前固定模板
|
||||
|
||||
为了避免两份协作文档再次变成长讨论稿，当前约定两边都采用统一结构：
|
||||
|
||||
- `待确认`
|
||||
- `已确认`
|
||||
- `阻塞`
|
||||
- `已完成`
|
||||
- `下一步`
|
||||
|
||||
并且每条尽量固定包含：
|
||||
|
||||
- 时间
|
||||
- 提出方
|
||||
- 当前事实
|
||||
- 需要对方确认什么
|
||||
- 当前状态
|
||||
|
||||
这样做的目的不是增加格式负担，而是保证：
|
||||
|
||||
- 三条线程都能快速扫描
|
||||
- 总控线程能快速识别优先级
|
||||
- 已确认事项不会反复讨论
|
||||
|
||||
---
|
||||
|
||||
## 3. 总控线程的职责
|
||||
|
||||
总控线程不替代前后端线程，而是负责：
|
||||
@@ -100,6 +126,21 @@
|
||||
- 正式设计文档
|
||||
- 阶段结论
|
||||
|
||||
### 3.3 当前总控线程的附加约束
|
||||
|
||||
总控线程需要持续做两件事：
|
||||
|
||||
- 读取并理解 [f2b.md](D:/dev/cmr-mini/f2b.md) 和 [b2f.md](D:/dev/cmr-mini/b2f.md) 的最新事实
|
||||
- 把已经收敛的跨线程结论回写到 `doc/` 正式文档
|
||||
|
||||
也就是说，总控线程不是“第三份协作文档”，而是：
|
||||
|
||||
- 主线维护者
|
||||
- 正式知识沉淀者
|
||||
- 交叉影响判断者
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## 4. 推荐协作顺序
|
||||
@@ -142,6 +183,8 @@
|
||||
- 以联调事实为主
|
||||
- 可频繁修改
|
||||
- 不要求体系化
|
||||
- 采用统一固定结构
|
||||
- 不承担正式设计说明职责
|
||||
|
||||
### 5.2 正式文档
|
||||
|
||||
@@ -255,3 +298,21 @@
|
||||
- 让并行开发不串线
|
||||
- 让重要结论沉淀下来
|
||||
- 让总控线程始终知道项目全貌
|
||||
|
||||
---
|
||||
|
||||
## 9. 当前执行状态
|
||||
|
||||
截至当前阶段，这套方式已经进入实际执行状态：
|
||||
|
||||
- 前端线程维护 [f2b.md](D:/dev/cmr-mini/f2b.md)
|
||||
- 后端线程维护 [b2f.md](D:/dev/cmr-mini/b2f.md)
|
||||
- 两份文档都已经按统一结构整理
|
||||
- 总控线程负责维护 [文档索引.md](D:/dev/cmr-mini/doc/文档索引.md) 和 `doc/` 下的正式文档
|
||||
|
||||
后续如果线程数量增加，或者联调链变复杂，优先仍然是：
|
||||
|
||||
- 先扩展协作文档约定
|
||||
- 再决定是否引入更重的流程工具
|
||||
|
||||
而不是先把协作体系做复杂。
|
||||
|
||||
390
f2b.md
390
f2b.md
@@ -1,233 +1,195 @@
|
||||
# F2B 协作清单
|
||||
|
||||
本文档由前端维护，用于记录：
|
||||
说明：
|
||||
|
||||
- 前端当前联调状态
|
||||
- 需要后端确认或配合的事项
|
||||
- 已明确的接口契约与运行时语义
|
||||
|
||||
约定：
|
||||
|
||||
- `f2b.md` 由前端维护
|
||||
- `b2f.md` 由后端维护
|
||||
- 双方只维护自己的文件
|
||||
- 边界不清的事项，先写入文档，再由你确认
|
||||
- 本文件由前端维护，写给后端
|
||||
- 只写“事实”和“请求”
|
||||
- 不写长讨论稿
|
||||
- 每条尽量包含：时间、提出方、当前事实、需要对方确认什么、状态
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前前端联调状态
|
||||
## 待确认
|
||||
|
||||
当前小程序侧已经接通：
|
||||
### F2B-001
|
||||
|
||||
- 微信小程序登录
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序当前按以下语义上报 session 结束状态：
|
||||
- 正常打终点完成 -> `finished`
|
||||
- 超时结束 -> `failed`
|
||||
- 主动退出 / 放弃恢复 -> `cancelled`
|
||||
- 需要对方确认什么：
|
||||
- backend 是否确认以上三态为正式语义
|
||||
- 状态：待确认
|
||||
|
||||
### F2B-002
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序已启用“放弃恢复 -> `finish(cancelled)`”
|
||||
- 调用时使用的是恢复快照里的旧 `sessionId/sessionToken`
|
||||
- 若上报失败，前端仍会放弃本地恢复，不阻塞用户
|
||||
- 需要对方确认什么：
|
||||
- backend 是否确认“放弃恢复”应记为 `cancelled`
|
||||
- 旧 `sessionToken` 在该场景下是否允许调用 `finish(cancelled)`
|
||||
- 状态：待确认
|
||||
|
||||
### F2B-003
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 联调和故障恢复场景下，`start` / `finish` 存在重复调用可能
|
||||
- 当前前端已经尽量去重，但无法完全避免网络重试和页面重进
|
||||
- 需要对方确认什么：
|
||||
- backend 是否按幂等方式处理 `start`
|
||||
- backend 是否按幂等方式处理 `finish`
|
||||
- 状态：待确认
|
||||
|
||||
### F2B-004
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 前端当前依赖以下 launch 字段：
|
||||
- `resolvedRelease.manifestUrl`
|
||||
- `resolvedRelease.releaseId`
|
||||
- `business.sessionId`
|
||||
- `business.sessionToken`
|
||||
- `business.sessionTokenExpiresAt`
|
||||
- 需要对方确认什么：
|
||||
- backend 后续如需调整这些字段名或层级，需先在 `b2f.md` 明确通知
|
||||
- 状态：待确认
|
||||
|
||||
### F2B-005
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- ongoing session 目前会影响：
|
||||
- `/me/entry-home`
|
||||
- `/events/{eventPublicID}/play`
|
||||
- `/sessions/{sessionPublicID}/result`
|
||||
- 需要对方确认什么：
|
||||
- `cancelled` 后不再作为 ongoing 返回
|
||||
- `failed` 后不再作为 ongoing 返回
|
||||
- `finished` 后结果摘要与首页摘要口径一致
|
||||
- 状态：待确认
|
||||
|
||||
---
|
||||
|
||||
## 已确认
|
||||
|
||||
### F2B-C001
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 正式联调时，前端以 backend `launch` 下发的 release/manifest 为准
|
||||
- 不再回退到本地 `event/*.json`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已确认
|
||||
|
||||
### F2B-C002
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 前后端协作文档改为双文件：
|
||||
- `f2b.md` 由前端维护
|
||||
- `b2f.md` 由后端维护
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已确认
|
||||
|
||||
---
|
||||
|
||||
## 阻塞
|
||||
|
||||
### F2B-B001
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 当前前端主链已基本可联调
|
||||
- 目前没有新的 backend 阻塞项
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已解决
|
||||
|
||||
---
|
||||
|
||||
## 已完成
|
||||
|
||||
### F2B-D001
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序已接通：
|
||||
- 登录
|
||||
- 首页聚合
|
||||
- 活动页 `play`
|
||||
- `launch -> 地图页`
|
||||
- `session start`
|
||||
- `session finish`
|
||||
- `session result`
|
||||
- 故障恢复提示与恢复继续
|
||||
- 故障恢复放弃
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
当前已确认不再是 backend 阻塞项：
|
||||
### F2B-D002
|
||||
|
||||
- `evt_demo_001` 的 release manifest 现在可正常加载
|
||||
- 地图页已经能正常拉起
|
||||
- 模拟定位 / 模拟日志的通道与连接问题，当前主要在小程序与模拟器侧处理
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序已接入故障恢复：
|
||||
- 检测未正常结束对局
|
||||
- 弹“继续恢复 / 放弃”
|
||||
- 继续恢复时恢复本地运行时快照
|
||||
- 放弃时清本地恢复，并上报 `finish(cancelled)`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
### F2B-D003
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- `evt_demo_001` 当前 release manifest 已恢复可用
|
||||
- 前端已能正常进入地图
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
---
|
||||
|
||||
## 2. 前端已按当前契约实现
|
||||
|
||||
### 2.1 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`
|
||||
|
||||
当前前端约束：
|
||||
|
||||
- 正式联调只认后端 `launch` 下发的 release / manifest
|
||||
- 不再回退到本地 `event/*.json` 样例路径
|
||||
- 如果 `manifestUrl` 无效，会直接在地图页报错
|
||||
|
||||
### 2.2 session 生命周期
|
||||
|
||||
前端当前已接：
|
||||
|
||||
- 进入运行态后自动上报 `session start`
|
||||
- 正常结束时上报 `finish(finished)`
|
||||
- 超时结束时上报 `finish(failed)`
|
||||
- 主动退出时上报 `finish(cancelled)`
|
||||
|
||||
### 2.3 故障恢复
|
||||
|
||||
前端当前已接：
|
||||
|
||||
- 检测到未正常结束对局时，弹出“继续恢复 / 放弃”
|
||||
- 点击“继续恢复”时恢复本地运行时快照
|
||||
- 点击“放弃”时：
|
||||
- 清理本地恢复快照
|
||||
- 并使用**恢复快照中的旧 sessionId/sessionToken** 向后端补报 `finish(cancelled)`
|
||||
|
||||
当前实现口径：
|
||||
|
||||
- 放弃恢复不会阻塞用户
|
||||
- 即使 backend 上报失败，前端也会继续放弃本地恢复
|
||||
- 失败时前端会明确提示“后端取消上报失败”
|
||||
|
||||
---
|
||||
|
||||
## 3. 需要 backend 当前确认 / 配合
|
||||
|
||||
## 3.1 固定 session 三态语义
|
||||
|
||||
请 backend 明确并固定：
|
||||
|
||||
- `finished`
|
||||
- `failed`
|
||||
- `cancelled`
|
||||
|
||||
前端当前使用口径：
|
||||
|
||||
- 正常打终点完成 -> `finished`
|
||||
- 超时结束 -> `failed`
|
||||
- 主动退出 / 放弃恢复 -> `cancelled`
|
||||
|
||||
如果 backend 计划使用其他语义，请先在 `b2f.md` 明确，不要直接改单接口行为。
|
||||
|
||||
## 3.2 确认“放弃恢复 -> cancelled”是官方语义
|
||||
|
||||
前端现在已经启用：
|
||||
|
||||
- 点击“放弃恢复”时，调用 `POST /sessions/{id}/finish`
|
||||
- 参数：`status=cancelled`
|
||||
|
||||
请 backend 确认：
|
||||
|
||||
1. 这是否就是官方的“放弃恢复 / 放弃本局”语义
|
||||
2. 旧 `sessionToken` 是否允许在恢复放弃场景继续调用 `finish(cancelled)`
|
||||
3. `cancelled` 后是否保证不再作为 `ongoingSession` 出现在：
|
||||
- `/me/entry-home`
|
||||
- `/events/{eventPublicID}/play`
|
||||
|
||||
## 3.3 保证 start / finish 幂等
|
||||
|
||||
请 backend 明确：
|
||||
|
||||
- `start` 重复调用是否安全
|
||||
- `finish` 重复调用是否安全
|
||||
|
||||
前端建议口径：
|
||||
|
||||
- `start`：如果 session 已在运行态，返回成功和当前 session
|
||||
- `finish`：如果 session 已进入终态，返回成功和当前 session/result
|
||||
|
||||
原因：
|
||||
|
||||
- 联调重试
|
||||
- 页面重进
|
||||
- 故障恢复补报
|
||||
- 用户重复点击
|
||||
|
||||
这些都很容易触发重复请求。
|
||||
|
||||
## 3.4 回归确认 ongoing session 口径一致
|
||||
|
||||
请 backend 回归确认以下接口对 ongoing session 的口径一致：
|
||||
|
||||
- `/me/entry-home`
|
||||
- `/events/{eventPublicID}/play`
|
||||
- `/sessions/{sessionPublicID}/result`
|
||||
|
||||
重点确认：
|
||||
|
||||
1. `cancelled` 后不再继续出现在 ongoing 入口
|
||||
2. `failed` 后不再继续出现在 ongoing 入口
|
||||
3. `finished` 后结果摘要和首页摘要保持一致
|
||||
|
||||
## 3.5 保持 launch 返回契约稳定
|
||||
|
||||
当前前端已经按既定结构接好 `launch`。
|
||||
|
||||
请 backend：
|
||||
|
||||
- 保持字段名稳定
|
||||
- 如需调整字段名或层级，先在 `b2f.md` 里给出变更说明
|
||||
- 尤其不要在未通知前端的情况下，改变：
|
||||
- `resolvedRelease.manifestUrl`
|
||||
- `business.sessionId`
|
||||
- `business.sessionToken`
|
||||
|
||||
---
|
||||
|
||||
## 4. P1 后续建议
|
||||
|
||||
## 4.1 用户身体数据接口
|
||||
|
||||
前端已经有 telemetry profile 合并能力。
|
||||
|
||||
backend 后续建议提供：
|
||||
|
||||
- 当前用户 body profile 查询接口
|
||||
|
||||
建议至少包含：
|
||||
|
||||
- `birthDate` 或 `heartRateAge`
|
||||
- `weightKg`
|
||||
- `restingHeartRateBpm`
|
||||
- `maxHeartRateBpm`（可选）
|
||||
|
||||
## 4.2 result 摘要字段容错
|
||||
|
||||
前端当前 finish 可能上报：
|
||||
|
||||
- `finalDurationSec`
|
||||
- `finalScore`
|
||||
- `completedControls`
|
||||
- `totalControls`
|
||||
- `distanceMeters`
|
||||
- `averageSpeedKmh`
|
||||
- `maxHeartRateBpm`
|
||||
|
||||
请 backend：
|
||||
|
||||
- 对可选字段做空值容忍
|
||||
- 不要因某个非关键字段缺失导致整局 finish 失败
|
||||
|
||||
## 4.3 workbench 增加恢复相关调试项
|
||||
|
||||
建议 backend workbench 后续增加：
|
||||
|
||||
- 将 session 标记为 `cancelled`
|
||||
- 查询当前用户 ongoing session
|
||||
- 查看最近一局状态流转
|
||||
|
||||
这样更利于故障恢复联调。
|
||||
|
||||
---
|
||||
|
||||
## 5. 当前前端需要 backend 反馈的最小集合
|
||||
|
||||
backend 现在只要先在 `b2f.md` 回 3 件事，前后端主链就能更稳：
|
||||
|
||||
1. `finished / failed / cancelled` 三态最终语义
|
||||
2. 放弃恢复时 `finish(cancelled)` 是否是正式方案
|
||||
3. `start / finish` 是否按幂等处理
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话结论
|
||||
|
||||
当前前端最需要 backend 配合的，不是更多新接口，而是：
|
||||
|
||||
> 先把 session 生命周期语义、放弃恢复语义和 ongoing session 口径完全定稳。
|
||||
## 下一步
|
||||
|
||||
### F2B-N001
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 当前最需要 backend 反馈的，是 session 生命周期相关语义
|
||||
- 需要对方确认什么：
|
||||
- 优先回复：
|
||||
- F2B-001
|
||||
- F2B-002
|
||||
- F2B-003
|
||||
- 状态：等待后端回复
|
||||
|
||||
### F2B-N002
|
||||
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 心率 / 卡路里个体化能力已在前端预留
|
||||
- 需要对方确认什么：
|
||||
- 后续是否提供用户身体数据接口
|
||||
- 状态：后续事项
|
||||
|
||||
Reference in New Issue
Block a user