整理前后端联调协作文档
This commit is contained in:
352
f2b.md
352
f2b.md
@@ -1,233 +1,195 @@
|
||||
# F2B 协作清单
|
||||
|
||||
本文档由前端维护，用于记录：
|
||||
说明：
|
||||
|
||||
- 前端当前联调状态
|
||||
- 需要后端确认或配合的事项
|
||||
- 已明确的接口契约与运行时语义
|
||||
|
||||
约定：
|
||||
|
||||
- `f2b.md` 由前端维护
|
||||
- `b2f.md` 由后端维护
|
||||
- 双方只维护自己的文件
|
||||
- 边界不清的事项，先写入文档，再由你确认
|
||||
- 本文件由前端维护，写给后端
|
||||
- 只写“事实”和“请求”
|
||||
- 不写长讨论稿
|
||||
- 每条尽量包含：时间、提出方、当前事实、需要对方确认什么、状态
|
||||
|
||||
---
|
||||
|
||||
## 1. 当前前端联调状态
|
||||
## 待确认
|
||||
|
||||
当前小程序侧已经接通：
|
||||
### F2B-001
|
||||
|
||||
- 微信小程序登录
|
||||
- 首页聚合
|
||||
- 活动页 `play`
|
||||
- `launch -> 地图页`
|
||||
- `session start`
|
||||
- `session finish`
|
||||
- `session result`
|
||||
- 故障恢复提示与恢复继续
|
||||
- 故障恢复放弃
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序当前按以下语义上报 session 结束状态：
|
||||
- 正常打终点完成 -> `finished`
|
||||
- 超时结束 -> `failed`
|
||||
- 主动退出 / 放弃恢复 -> `cancelled`
|
||||
- 需要对方确认什么：
|
||||
- backend 是否确认以上三态为正式语义
|
||||
- 状态：待确认
|
||||
|
||||
当前已确认不再是 backend 阻塞项：
|
||||
### F2B-002
|
||||
|
||||
- `evt_demo_001` 的 release manifest 现在可正常加载
|
||||
- 地图页已经能正常拉起
|
||||
- 模拟定位 / 模拟日志的通道与连接问题，当前主要在小程序与模拟器侧处理
|
||||
- 时间：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` 后结果摘要与首页摘要口径一致
|
||||
- 状态：待确认
|
||||
|
||||
---
|
||||
|
||||
## 2. 前端已按当前契约实现
|
||||
## 已确认
|
||||
|
||||
### 2.1 launch 契约
|
||||
### F2B-C001
|
||||
|
||||
前端当前按以下字段消费：
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 正式联调时，前端以 backend `launch` 下发的 release/manifest 为准
|
||||
- 不再回退到本地 `event/*.json`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已确认
|
||||
|
||||
- `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`
|
||||
### F2B-C002
|
||||
|
||||
当前前端约束：
|
||||
|
||||
- 正式联调只认后端 `launch` 下发的 release / manifest
|
||||
- 不再回退到本地 `event/*.json` 样例路径
|
||||
- 如果 `manifestUrl` 无效，会直接在地图页报错
|
||||
|
||||
### 2.2 session 生命周期
|
||||
|
||||
前端当前已接：
|
||||
|
||||
- 进入运行态后自动上报 `session start`
|
||||
- 正常结束时上报 `finish(finished)`
|
||||
- 超时结束时上报 `finish(failed)`
|
||||
- 主动退出时上报 `finish(cancelled)`
|
||||
|
||||
### 2.3 故障恢复
|
||||
|
||||
前端当前已接：
|
||||
|
||||
- 检测到未正常结束对局时，弹出“继续恢复 / 放弃”
|
||||
- 点击“继续恢复”时恢复本地运行时快照
|
||||
- 点击“放弃”时：
|
||||
- 清理本地恢复快照
|
||||
- 并使用**恢复快照中的旧 sessionId/sessionToken** 向后端补报 `finish(cancelled)`
|
||||
|
||||
当前实现口径：
|
||||
|
||||
- 放弃恢复不会阻塞用户
|
||||
- 即使 backend 上报失败，前端也会继续放弃本地恢复
|
||||
- 失败时前端会明确提示“后端取消上报失败”
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 前后端协作文档改为双文件：
|
||||
- `f2b.md` 由前端维护
|
||||
- `b2f.md` 由后端维护
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已确认
|
||||
|
||||
---
|
||||
|
||||
## 3. 需要 backend 当前确认 / 配合
|
||||
## 阻塞
|
||||
|
||||
## 3.1 固定 session 三态语义
|
||||
### F2B-B001
|
||||
|
||||
请 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`
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 当前前端主链已基本可联调
|
||||
- 目前没有新的 backend 阻塞项
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已解决
|
||||
|
||||
---
|
||||
|
||||
## 4. P1 后续建议
|
||||
## 已完成
|
||||
|
||||
## 4.1 用户身体数据接口
|
||||
### F2B-D001
|
||||
|
||||
前端已经有 telemetry profile 合并能力。
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序已接通：
|
||||
- 登录
|
||||
- 首页聚合
|
||||
- 活动页 `play`
|
||||
- `launch -> 地图页`
|
||||
- `session start`
|
||||
- `session finish`
|
||||
- `session result`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
backend 后续建议提供：
|
||||
### F2B-D002
|
||||
|
||||
- 当前用户 body profile 查询接口
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 小程序已接入故障恢复：
|
||||
- 检测未正常结束对局
|
||||
- 弹“继续恢复 / 放弃”
|
||||
- 继续恢复时恢复本地运行时快照
|
||||
- 放弃时清本地恢复，并上报 `finish(cancelled)`
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
建议至少包含：
|
||||
### F2B-D003
|
||||
|
||||
- `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
|
||||
- 查看最近一局状态流转
|
||||
|
||||
这样更利于故障恢复联调。
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- `evt_demo_001` 当前 release manifest 已恢复可用
|
||||
- 前端已能正常进入地图
|
||||
- 需要对方确认什么：
|
||||
- 无
|
||||
- 状态：已完成
|
||||
|
||||
---
|
||||
|
||||
## 5. 当前前端需要 backend 反馈的最小集合
|
||||
## 下一步
|
||||
|
||||
backend 现在只要先在 `b2f.md` 回 3 件事，前后端主链就能更稳：
|
||||
### F2B-N001
|
||||
|
||||
1. `finished / failed / cancelled` 三态最终语义
|
||||
2. 放弃恢复时 `finish(cancelled)` 是否是正式方案
|
||||
3. `start / finish` 是否按幂等处理
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 当前最需要 backend 反馈的，是 session 生命周期相关语义
|
||||
- 需要对方确认什么：
|
||||
- 优先回复：
|
||||
- F2B-001
|
||||
- F2B-002
|
||||
- F2B-003
|
||||
- 状态：等待后端回复
|
||||
|
||||
---
|
||||
### F2B-N002
|
||||
|
||||
## 6. 一句话结论
|
||||
|
||||
当前前端最需要 backend 配合的，不是更多新接口，而是：
|
||||
|
||||
> 先把 session 生命周期语义、放弃恢复语义和 ongoing session 口径完全定稳。
|
||||
- 时间：2026-04-01
|
||||
- 提出方：前端
|
||||
- 当前事实：
|
||||
- 心率 / 卡路里个体化能力已在前端预留
|
||||
- 需要对方确认什么：
|
||||
- 后续是否提供用户身体数据接口
|
||||
- 状态：后续事项
|
||||
|
||||
Reference in New Issue
Block a user