zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
af43beadb05badf4139beb5c368b833bbf9bd6d1
cmr-mini/backend/docs/前后端联调清单.md

8.9 KiB
Raw Blame History

前后端联调清单

文档版本：v1.0 最后更新：2026-04-02

1. 目的

这份清单只回答三件事：

  1. 小程序当前已经具备哪些接后端的前置能力
  2. backend 当前已经提供了哪些可联调接口
  3. 哪些链路已经能接，哪些链路还缺适配

本文不讨论未来大而全后台方案，只服务当前联调落地。

2. 当前结论

当前状态可以概括成一句话：

backend 业务主链已经可联调；小程序地图运行内核也已经成型；两边之间还缺一层业务接入和会话上报适配。

也就是说：

  • 登录、活动详情、launch、session、result 这一条后端链已经可用
  • 小程序地图页已经支持携带 configUrl / releaseId / sessionId / sessionToken
  • 但小程序当前仍主要走本地 demo / 直连 OSS manifest
  • 真正的“后端 launch -> 地图页 -> session start/finish/result”还没有正式接上

3. 小程序当前已具备的联调基础

3.1 启动信封已经成型

地图页不是只吃一个 configUrl，而是吃一份启动信封：

当前结构：

  • config.configUrl
  • config.configLabel
  • config.configChecksumSha256
  • config.releaseId
  • config.routeCode
  • business.source
  • business.competitionId
  • business.eventId
  • business.launchRequestId
  • business.participantId
  • business.sessionId
  • business.sessionToken
  • business.sessionTokenExpiresAt
  • business.realtimeEndpoint
  • business.realtimeToken

这意味着：

  • backend launch 返回的数据结构已经能自然装进小程序地图启动链
  • 地图页并不需要重构启动模型，只需要把业务页接到 GameLaunchEnvelope

3.2 地图页已经支持远端 manifest 启动

当前地图页会：

  1. 解析 GameLaunchEnvelope
  2. 调 loadRemoteMapConfig(configUrl)
  3. 编译 runtime profile
  4. 启动 MapEngine

所以只要后端能给出：

  • manifestUrl
  • releaseId
  • configChecksumSha256

地图页就可以直接跑。

3.3 会话态字段已经进入地图页

地图页当前已经能接收并持有：

  • sessionId
  • sessionToken
  • sessionTokenExpiresAt

这说明后面接：

  • POST /sessions/{id}/start
  • POST /sessions/{id}/finish

不需要再改地图启动协议。

3.4 故障恢复也已经具备会话上下文承载

故障恢复快照当前会保留：

  • launchEnvelope
  • 运行态快照

这意味着一旦接入后端 session 后，恢复链也可以继续沿用同一份 launchEnvelope。

4. backend 当前已具备的联调基础

4.1 路由主链已落地

当前已实现：

  • POST /auth/login/wechat-mini
  • GET /me/entry-home
  • GET /events/{eventPublicID}/play
  • POST /events/{eventPublicID}/launch
  • POST /sessions/{sessionPublicID}/start
  • POST /sessions/{sessionPublicID}/finish
  • GET /sessions/{sessionPublicID}/result
  • GET /me/results

4.2 launch 返回结构已贴近客户端

当前 launch 返回重点：

  • launch.resolvedRelease.releaseId
  • launch.resolvedRelease.manifestUrl
  • launch.resolvedRelease.manifestChecksumSha256
  • launch.business.sessionId
  • launch.business.sessionToken

这和小程序 GameLaunchEnvelope 基本是同一语义。

4.3 session 运行态和结果态已分离

当前已经区分：

  • 业务登录态：access_token
  • 局内运行态：sessionToken

这对地图页是对的，因为地图页真正需要的是：

  • 进入前有业务 token
  • 进入后局内动作用 sessionToken

4.4 开发 workbench 已可用于联调

当前 workbench 已能串：

  • bootstrap
  • auth
  • entry/home
  • event play / launch
  • session start / finish / detail
  • result 查询

这对前后端联调非常有价值，说明后端已经不是“只看文档”阶段。

5. 当前已经能接的链路

5.1 P0：登录与业务页前置链

可接：

  1. 小程序 wx.login
  2. POST /auth/login/wechat-mini
  3. 拿到 accessToken
  4. 调 GET /me/entry-home
  5. 调 GET /events/{eventPublicID}/play

当前缺口：

  • 小程序还没有正式业务页 API 适配层
  • 还没有统一 token 持久化与请求封装

5.2 P0：launch 进入地图

可接：

  1. 前置业务页拿到 event play
  2. 调 POST /events/{eventPublicID}/launch
  3. 把返回结果映射成 GameLaunchEnvelope
  4. navigateTo('/pages/map/map?...')

当前缺口：

  • 还没有一层 backend launch -> GameLaunchEnvelope 的适配函数
  • 当前 gameLaunch.ts 仍偏 demo/static config 驱动

5.3 P0：finish 回传结果

可接：

  1. 地图页结束一局
  2. 提取结果摘要
  3. 用 sessionId + sessionToken 调 POST /sessions/{id}/finish
  4. 业务页或结果页再查 GET /sessions/{id}/result

当前缺口：

  • 小程序本地结果页已经有摘要，但还没有正式调用 backend finish
  • finish payload 和本地 resultSummary 之间还需要一层映射

6. 当前还不能说已经接通的链路

6.1 配置后台 source/build/release

backend 当前已经有：

  • 表结构
  • 文档模型

但还没有真正开放：

  • config source
  • build
  • release assets
  • preview launch

也就是说：

配置后台链还不能联调，只能联业务主链。

6.2 body profile / 遥测个体化

小程序已经有：

  • 身体数据入口
  • 遥测 runtime profile

backend 文档里也规划了：

  • 用户身体资料

但当前接口清单里还没有明确的 body profile 读接口落到小程序链上，所以这条还不能算当前联调主线。

7. 当前最大的接口适配缺口

我认为目前最大缺口只有 4 个：

7.1 业务 API 客户端缺失

小程序当前缺：

  • 统一 request 封装
  • token 持久化
  • access token 刷新
  • backend DTO -> 小程序 view model 适配

7.2 launch 适配层缺失

需要一层明确的转换：

LaunchResponse -> GameLaunchEnvelope

这里最适合单独做成一个小模块，而不是散落在页面里。

7.3 session finish 映射缺失

地图页当前本地已经有：

  • 用时
  • 分数
  • 完成点数
  • 里程
  • 速度
  • 最大心率

但还没有一个稳定函数把它映射为 backend finish payload。

7.4 业务结果页与地图结果页还未打通

现在地图页已经有自己的结果页。

后面要决定：

  • 地图页结果页先本地展示，再异步回传
  • 还是 finish 成功后跳业务结果页

这件事需要前后端统一策略。

8. 推荐联调顺序

建议按下面顺序推进，不要跳步：

第一步：接微信小程序登录

目标：

  • 小程序拿到 accessToken
  • 能请求鉴权接口

第二步：接 event play

目标：

  • 小程序业务页能拿到：
    • event
    • resolvedRelease
    • play.canLaunch
    • play.ongoingSession

第三步：接 launch -> map

目标：

  • 从后端 launch 返回直接进入地图
  • 不再靠 demo preset 手工切配置

第四步：接 start / finish / result

目标：

  • 开赛后能回传 start
  • 结束后能回传 finish
  • 结果页能查 backend result

第五步：再考虑 ongoing session 恢复

目标：

  • backend ongoing session
  • 本地故障恢复

两条链统一口径

9. 当前已落地的小程序联调适配

小程序侧当前已经补了第一批适配层：

当前已具备：

  • 后端 base URL 本地持久化
  • access / refresh token 本地持久化
  • 微信小程序登录请求封装
  • event play 请求封装
  • launch -> GameLaunchEnvelope 适配
  • 从首页直接 launch 进入地图
  • 地图页 session start / finish 上报接入

因此当前主链已从“可分析”进入“可实测”。

10. 我建议的最近行动项

如果开始联调，我建议先做这 3 件事：

  1. 新增小程序 backendApi 请求层
    先只包 auth / event play / launch / session finish

  2. 新增 launchAdapter
    把 backend launch 响应稳定转成 GameLaunchEnvelope

  3. 新增 finishAdapter
    把地图页结果摘要稳定转成 backend finish payload

这三件做完，前后端主链就能真正接起来。

11. 一句话结论

当前最真实的进度判断是：

backend 业务后端主链已经进入可联调阶段；小程序地图运行内核也已经具备承接能力；下一步最值钱的是补小程序业务 API 层和 launch/finish 两个适配器。

Reference in New Issue View Git Blame Copy Permalink