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