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 确认：

这是否就是官方的“放弃恢复 / 放弃本局”语义
旧 sessionToken 是否允许在恢复放弃场景继续调用 finish(cancelled)
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

重点确认：

cancelled 后不再继续出现在 ongoing 入口
failed 后不再继续出现在 ongoing 入口
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 件事，前后端主链就能更稳：

finished / failed / cancelled 三态最终语义
放弃恢复时 finish(cancelled) 是否是正式方案
start / finish 是否按幂等处理

6. 一句话结论

当前前端最需要 backend 配合的，不是更多新接口，而是：

先把 session 生命周期语义、放弃恢复语义和 ongoing session 口径完全定稳。

f2b.md 5.6 KB Historia Czysty