Add backend foundation and config-driven workbench
This commit is contained in:
255
backend/docs/todolist.md
Normal file
255
backend/docs/todolist.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# 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 运行态语义和故障恢复放弃语义定稳，再继续扩后台配置系统。
|
||||
Reference in New Issue
Block a user