234 lines
5.6 KiB
Markdown
234 lines
5.6 KiB
Markdown
# F2B 协作清单
|
||
|
||
本文档由前端维护，用于记录：
|
||
|
||
- 前端当前联调状态
|
||
- 需要后端确认或配合的事项
|
||
- 已明确的接口契约与运行时语义
|
||
|
||
约定：
|
||
|
||
- `f2b.md` 由前端维护
|
||
- `b2f.md` 由后端维护
|
||
- 双方只维护自己的文件
|
||
- 边界不清的事项，先写入文档，再由你确认
|
||
|
||
---
|
||
|
||
## 1. 当前前端联调状态
|
||
|
||
当前小程序侧已经接通：
|
||
|
||
- 微信小程序登录
|
||
- 首页聚合
|
||
- 活动页 `play`
|
||
- `launch -> 地图页`
|
||
- `session start`
|
||
- `session finish`
|
||
- `session result`
|
||
- 故障恢复提示与恢复继续
|
||
- 故障恢复放弃
|
||
|
||
当前已确认不再是 backend 阻塞项：
|
||
|
||
- `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 口径完全定稳。
|