# Backend TodoList
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 1. 目标

这份 TodoList 只列当前需要 backend 配合联调和近期应推进的事项。

原则：

- 不重复写已经稳定可用的能力
- 优先写会影响前后端联调闭环的点
- 边界不清的事项单独标记“需确认”

## 2. 当前联调现状

当前已经可联调的主链：

- 微信小程序登录
- `GET /events/{eventPublicID}/play`
- `POST /events/{eventPublicID}/launch`
- `POST /sessions/{sessionPublicID}/start`
- `POST /sessions/{sessionPublicID}/finish`
- `GET /sessions/{sessionPublicID}/result`

小程序侧已经具备：

- backend 地址和 token 持久化
- `launch -> GameLaunchEnvelope` 适配
- 进入地图后自动上报 `session start`
- 对局结束后自动上报 `session finish`

所以 backend 现在最重要的不是再扩散接口，而是把当前契约和语义收稳。

当前已确认不再阻塞主链的事项：

- `evt_demo_001` 的 release manifest 现已可正常加载
- 小程序已能进入地图
- 模拟定位 / 调试日志问题已回到小程序与模拟器侧，不再属于 backend 当前阻塞

前端当前需要配合的事项：

- 正式联调时始终以 `launch.resolvedRelease.manifestUrl` 为准，不再回退到本地样例配置路径
- 如果再出现配置加载失败，反馈完整上下文：
  - `eventPublicID`
  - `releaseId`
  - `manifestUrl`
  - 页面报错文案
  - 控制台 / 网络日志
- 当前 demo 联调建议统一使用：
  - `eventPublicID = evt_demo_001`
  - `channelCode = mini-demo`
  - `channelType = wechat_mini`

## 3. P0 已完成

## 3.0 固定 session 状态语义

当前 backend 已明确并固定：

- `finished`
- `failed`
- `cancelled`

建议当前口径：

- 正常打终点完成：`finished`
- 超时结束：`failed`
- 主动退出 / 放弃恢复：`cancelled`

说明：

- 小程序现在已经按这个方向接
- 如果 backend 想改这 3 个状态语义，需要先讨论，不要单边改

## 3.1 明确“放弃恢复”的后端处理

当前小程序本地恢复逻辑已经是：

- 进入程序检测到未正常结束对局
- 弹确认框
- 玩家可“继续恢复”或“放弃”

现在本地“放弃”只会清除本地恢复快照。

backend 已确认的目标语义是：

> 玩家点击“放弃恢复”后，这一局是否应同时在业务后端标记为 `cancelled`。

当前结论：

- **是，应标记为 `cancelled`**

原因：

- 否则 `ongoingSession` 会继续存在
- `/events/{id}/play` 和 `/me/entry-home` 可能一直把它当成可继续的局
- 会和小程序本地“已放弃”产生语义分叉

当前 backend 已收口：

1. `POST /sessions/{id}/finish` 使用 `status=cancelled` 是否就是官方放弃语义
2. 如果客户端持有旧 `sessionToken`，恢复放弃时是否允许直接调用 `finish(cancelled)`
3. `cancelled` 后，`event play` 和 `entry-home` 中不再返回为 `ongoingSession`

备注：

- 小程序侧现在可以把“点击放弃恢复”正式接成同步调用 `finish(cancelled)`。

## 3.2 保证 start / finish 幂等与重复调用安全

联调和真实环境里，以下情况很常见：

- 网络重试
- 页面重进
- 故障恢复后二次补报
- 用户重复点击

当前 backend 已确认：

- `start` 重复调用的幂等语义
- `finish` 重复调用的幂等语义

当前实现：

- `start`：如果已 `running`，返回当前 session，视为成功
- `finish`：如果已进入终态，返回当前 session/result，视为成功

目的：

- 不把客户端补偿逻辑变成一堆冲突分支

## 3.3 固定 `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`

backend 现在需要做的是：

- 先保持这些字段名稳定
- 如果要调整命名或层级，先沟通

前端当前需要做的是：

- 只消费当前已约定字段
- 不额外推断 release URL
- 不把本地样例配置路径混进正式 launch 流程
- 如果字段缺失或命名变化，直接在联调清单里标阻塞

## 4. P1 应尽快做

## 4.1 给首页 / play / result 的 ongoing 语义再做一次回归确认

当前前端已经开始走：

- 首页聚合
- `event play`
- `launch`
- `session start / finish`
- 本地故障恢复

backend 建议再回归确认这几个接口对“进行中 session”的口径一致：

- `/me/entry-home`
- `/events/{eventPublicID}/play`
- `/sessions/{sessionPublicID}/result`

重点确认：

1. `cancelled` 后不再继续出现在 ongoing 入口
2. `failed` 后不再继续出现在 ongoing 入口
3. `finished` 后结果页与首页摘要字段一致

## 4.2 增加用户身体资料读取接口

小程序侧已经有：

- telemetry profile 合并入口
- 心率/卡路里计算逻辑

backend 下一步建议提供：

- 当前用户 body profile 查询接口

建议返回至少包含：

- `birthDate` 或 `heartRateAge`
- `weightKg`
- `restingHeartRateBpm`
- `maxHeartRateBpm`（可选）

这样后面心率页和消耗估算就能真实接业务数据。

## 4.3 给 `session result` 补一点稳定摘要字段校验

客户端现在会上报：

- `finalDurationSec`
- `finalScore`
- `completedControls`
- `totalControls`
- `distanceMeters`
- `averageSpeedKmh`

backend 建议补两件事：

- 合理性校验
- 空值容忍

不要因为某个可选字段缺失就整局 finish 失败。

## 4.4 dev workbench 增加一组“恢复 / 取消恢复”场景按钮

当前 workbench 已经很好用了。

建议后续再补：

- 标记 session 为 `cancelled`
- 查询 ongoing session
- 快速查看某个用户最新 session 状态

这会很适合配合小程序故障恢复联调。

## 4.5 前端预埋“放弃恢复”调用位

这项先预埋，不要先自行定语义。

前端建议准备好：

- 在“放弃恢复”按钮点击后，预留调用 `finish(cancelled)` 的位置
- 但是否正式启用，要等 backend 把 `cancelled` 语义确认完

这样一旦 backend 确认语义，小程序就能快速切过去，不需要再改一轮页面流程。

## 5. P2 下一阶段

## 5.1 配置后台 source / build / release 真正开始做

当前已经有：

- 表结构
- 架构文档

还缺：

- source CRUD
- build 触发
- manifest 产物生成
- release 发布
- asset index 查询

这个建议在当前主链联稳之后再推进。

## 5.2 page / cards / competition 等业务对象继续长出来

这部分不是当前联调阻塞项，但后面会成为业务壳的重要组成。

## 5.3 兼顾未来 APP 的统一后端约束

backend 后续建设需要继续坚持：

- 不做“小程序专用后端”
- 用户模型保持平台级
- `event / release / session / result` 不按终端拆两套
- 终端差异只通过上下文字段和运行时适配处理

建议优先保持：

- 业务接口统一
- 配置发布结构统一
- 结果沉淀结构统一

这样后面 APP 接入时不会推翻现有 backend 结构。

## 6. 需要先讨论再动的边界

这些事项 backend 不建议自己先拍板：

### 6.1 `failed` 是否专指超时

当前建议是：

- 超时 -> `failed`
- 主动退出 / 放弃恢复 -> `cancelled`

如果 backend 有别的语义方案，需要先统一。

### 6.2 放弃恢复是否一定写后端

我个人建议写后端，并落成 `cancelled`。

但如果 backend 团队认为：

- 放弃恢复只影响本地
- 业务上仍允许以后继续从服务端 ongoing session 恢复

那就必须明确告知客户端，不然两边会冲突。

### 6.3 result 页是以后继续本地展示，还是跳业务结果页

当前客户端是本地结果页。

backend 后面如果要接业务结果页，最好提前定：

- finish 成功后是否仍停留地图内结果页
- 还是跳业务壳结果页

## 7. 我建议的最近动作

backend 现在最值得先做的，不是扩接口，而是先确认下面 3 条：

1. `finished / failed / cancelled` 三态语义
2. 放弃恢复是否写 `cancelled`
3. `start / finish` 是否按幂等处理

这 3 条一旦确定，前后端联调会顺很多。

## 8. 一句话结论

当前 backend 最重要的任务不是“再加更多接口”，而是：

> 先把 session 运行态语义、放弃恢复语义和 ongoing session 口径定稳，再继续扩后台配置系统。