cmr-mini/f2b.md

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 口径完全定稳。