337 lines
8.6 KiB
Markdown
337 lines
8.6 KiB
Markdown
# Backend TodoList
|
||
> 文档版本：v1.0
|
||
> 最后更新：2026-04-02
|
||
|
||
|
||
## 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`。
|
||
|
||
我建议 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.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 口径定稳，再继续扩后台配置系统。
|
||
|