cmr-mini/backend/docs/todolist.md

Backend TodoList

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 现在最重要的不是再扩散接口，而是把当前契约和语义收稳。

3. P0 必做

3.1 固定 session 状态语义

需要 backend 明确并固定：

• finished
• failed
• cancelled

建议当前口径：

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

说明：

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

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

这是当前最值得后端配合确认的一点。

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

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

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

backend 需要确认的目标语义是：

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

我建议 backend 采用：

• 是，应标记为 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

备注：

• 如果 backend 认可这套语义，小程序侧下一步就可以把“点击放弃恢复”改成同步调用 finish(cancelled)。

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

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

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

backend 需要确认：

• start 重复调用的幂等语义
• finish 重复调用的幂等语义

建议：

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

目的：

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

3.4 固定 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 现在需要做的是：

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

4. P1 应尽快做

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

小程序侧已经有：

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

backend 下一步建议提供：

• 当前用户 body profile 查询接口

建议返回至少包含：

• birthDate 或 heartRateAge
• weightKg
• restingHeartRateBpm
• maxHeartRateBpm（可选）

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

4.2 给 session result 补一点稳定摘要字段校验

客户端现在会上报：

• finalDurationSec
• finalScore
• completedControls
• totalControls
• distanceMeters
• averageSpeedKmh

backend 建议补两件事：

• 合理性校验
• 空值容忍

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

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

当前 workbench 已经很好用了。

建议后续再补：

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

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

5. P2 下一阶段

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

当前已经有：

• 表结构
• 架构文档

还缺：

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

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

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

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

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 运行态语义和故障恢复放弃语义定稳，再继续扩后台配置系统。