Add backend foundation and config-driven workbench

2026-04-01 15:01:44 +08:00
parent 88b8f05f03
commit 94a1f0ba78
68 changed files with 10833 additions and 0 deletions
--- a/todolist.md
+++ b/todolist.md
@@ -0,0 +1,292 @@
+# CMR 联调协作清单
+
+本文档用于后端、前端和你之间的联调协作。
+
+约定：
+
+- 所有新开发事项先进入 `待确认事项`，只有你确认后才能移动到 `已确认可开发`
+- 我会在这里提出后端接入要求、接口变更和联调建议
+- 前端同学可以在这里补页面进度、阻塞问题和接口反馈
+- 这里是协作清单，不替代正式接口文档和方案文档
+
+状态说明：
+
+- `待确认`：已提出，但未获你确认
+- `已确认`：你已确认，可以进入开发
+- `联调中`：前后端已经开始接
+- `已完成`：开发和联调完成
+- `阻塞`：存在明确阻塞项
+
+---
+
+## 1. 当前联调目标
+
+当前优先目标：
+
+- 把前台壳层的登录、首页、活动详情、开始前准备、结果页先接通
+- 让配置导入、preview、publish、launch 这条配置驱动链可被稳定验证
+- 用 workbench 和接口文档降低前后端联调成本
+
+当前后端已经具备：
+
+- 统一登录
+- 微信小程序登录
+- 手机号绑定与账号合并
+- 入口解析
+- 首页聚合
+- 活动详情与 play 聚合
+- launch / session / result 主链路
+- 配置导入 / preview / publish
+- API workbench
+
+相关文档：
+
+- [后端总览 README](D:/dev/cmr-mini/backend/README.md)
+- [接口清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
+- [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)
+- [配置管理方案](D:/dev/cmr-mini/backend/docs/配置管理方案.md)
+
+---
+
+## 2. 待确认事项
+
+### T-001 首页首批页面范围
+
+- 状态：`待确认`
+- 建议负责人：你
+- 说明：建议前端首批只接这 5 个页面，不要同时铺太多页面
+- 建议范围：
+  - 登录页
+  - 首页
+  - 活动详情页
+  - 开始前准备页
+  - 结果页
+
+### T-002 配置驱动联调入口
+
+- 状态：`待确认`
+- 建议负责人：你
+- 说明：建议首批统一使用 `evt_demo_001` 做联调，不在前端直接读根目录 `event` 文件，统一由后端 `release/manifest` 下发
+
+### T-003 前端联调顺序
+
+- 状态：`待确认`
+- 建议负责人：你
+- 说明：建议按这个顺序接，避免页面壳层先做散
+- 建议顺序：
+  - 登录
+  - 首页
+  - 活动详情 / play
+  - launch
+  - session start / finish
+  - result
+
+---
+
+## 3. 已确认可开发
+
+暂无。
+
+---
+
+## 4. 前端待接接口
+
+### F-001 登录页接入
+
+- 状态：`待确认`
+- 建议负责人：前端
+- 页面：登录页
+- 接口：
+  - `POST /auth/login/wechat-mini`
+  - `POST /auth/sms/send`
+  - `POST /auth/login/sms`
+  - `POST /auth/bind/mobile`
+- 说明：
+  - APP 以手机号登录为主
+  - 小程序可先微信登录，后续再绑定手机号
+
+### F-002 首页接入
+
+- 状态：`待确认`
+- 建议负责人：前端
+- 页面：首页
+- 接口：
+  - `GET /me/entry-home`
+- 说明：
+  - 首页不要自己拼多个接口
+  - 直接以聚合接口为主
+
+### F-003 活动详情与开始前准备接入
+
+- 状态：`待确认`
+- 建议负责人：前端
+- 页面：活动详情页、开始前准备页
+- 接口：
+  - `GET /events/{eventPublicID}/play`
+  - `POST /events/{eventPublicID}/launch`
+- 说明：
+  - `play` 用于决定按钮文案和状态
+  - `launch` 成功后进入游戏
+
+### F-004 结果页接入
+
+- 状态：`待确认`
+- 建议负责人：前端
+- 页面：结果页
+- 接口：
+  - `GET /sessions/{sessionPublicID}/result`
+  - `GET /me/results`
+- 说明：
+  - 单局页用 `session result`
+  - 列表页用 `my results`
+
+### F-005 我的页接入
+
+- 状态：`待确认`
+- 建议负责人：前端
+- 页面：我的页
+- 接口：
+  - `GET /me/profile`
+- 说明：
+  - 不建议前端自己拼绑定信息和最近记录
+
+---
+
+## 5. 后端待补能力
+
+### B-001 发布后的 release 管理
+
+- 状态：`待确认`
+- 建议负责人：后端
+- 说明：当前已经支持 import / preview / publish，但还缺正式的 release 列表、回滚和历史查看
+
+### B-002 更通用的 play context
+
+- 状态：`待确认`
+- 建议负责人：后端
+- 说明：当前 launch 仍是 `event` 入口为主，后续需要抽象成更通用的 `play context -> launch`
+
+### B-003 配置校验报告
+
+- 状态：`待确认`
+- 建议负责人：后端
+- 说明：当前 preview 已可用，但还缺面向配置运营的结构化校验报告
+
+---
+
+## 6. 当前后端已可联调接口
+
+登录与用户：
+
+- `POST /auth/sms/send`
+- `POST /auth/login/sms`
+- `POST /auth/login/wechat-mini`
+- `POST /auth/bind/mobile`
+- `GET /me`
+- `GET /me/profile`
+
+首页与入口：
+
+- `GET /entry/resolve`
+- `GET /home`
+- `GET /cards`
+- `GET /me/entry-home`
+
+活动与游戏启动：
+
+- `GET /events/{eventPublicID}`
+- `GET /events/{eventPublicID}/play`
+- `POST /events/{eventPublicID}/launch`
+
+局内与结果：
+
+- `GET /sessions/{sessionPublicID}`
+- `POST /sessions/{sessionPublicID}/start`
+- `POST /sessions/{sessionPublicID}/finish`
+- `GET /sessions/{sessionPublicID}/result`
+- `GET /me/sessions`
+- `GET /me/results`
+
+配置管理：
+
+- `GET /dev/config/local-files`
+- `POST /dev/events/{eventPublicID}/config-sources/import-local`
+- `POST /dev/config-builds/preview`
+- `POST /dev/config-builds/publish`
+
+开发工具：
+
+- `POST /dev/bootstrap-demo`
+- `GET /dev/workbench`
+
+---
+
+## 7. 联调建议
+
+### S-001 前端联调统一入口
+
+- 状态：`待确认`
+- 建议负责人：后端 + 前端
+- 说明：建议首批所有联调都通过 demo 数据进行，统一使用：
+  - `channelCode=mini-demo`
+  - `channelType=wechat_mini`
+  - `eventPublicID=evt_demo_001`
+
+### S-002 配置驱动约束
+
+- 状态：`待确认`
+- 建议负责人：后端 + 前端
+- 说明：
+  - 前端进入游戏时不要直接拼根目录配置文件路径
+  - 必须使用后端下发的：
+    - `releaseId`
+    - `manifestUrl`
+    - `manifestChecksumSha256`
+
+### S-003 联调工具优先级
+
+- 状态：`已确认`
+- 建议负责人：后端
+- 说明：
+  - 日常联调优先使用 workbench
+  - 接口说明优先看 workbench 里的 `API 列表`
+  - 深入字段说明再看 [接口清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
+
+---
+
+## 8. 阻塞记录
+
+暂无。
+
+---
+
+## 9. 完成记录
+
+### R-001 后端主链路已打通
+
+- 状态：`已完成`
+- 负责人：后端
+- 说明：
+  - 登录
+  - 首页聚合
+  - 活动 play
+  - launch
+  - session
+  - result
+
+### R-002 配置 import / preview / publish 已打通
+
+- 状态：`已完成`
+- 负责人：后端
+- 说明：
+  - 已验证 `import-local -> preview -> publish -> launch`
+
+### R-003 API workbench 已上线
+
+- 状态：`已完成`
+- 负责人：后端
+- 说明：
+  - 已支持中文 API 列表
+  - 已支持 quick flows
+  - 已支持场景保存
+  - 已支持配置发布链调试