zhangyan/cmr-mini
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

同步前后端联调与文档更新

Browse Source
This commit is contained in:
zhangyan
2026-04-02 09:25:05 +08:00
parent af43beadb0
commit 6964e26ec9
113 changed files with 4317 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
backend/docs/README.md
View File

@@ -1,6 +1,6 @@
# Backend Docs
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
这套文档服务两个目的：
@@ -16,9 +16,10 @@
4. [数据模型](D:/dev/cmr-mini/backend/docs/数据模型.md)
5. [配置管理方案](D:/dev/cmr-mini/backend/docs/配置管理方案.md)
6. [资源对象与目录方案](D:/dev/cmr-mini/backend/docs/资源对象与目录方案.md)
7. [前后端联调清单](D:/dev/cmr-mini/backend/docs/前后端联调清单.md)
8. [TodoList](D:/dev/cmr-mini/backend/docs/todolist.md)
9. [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)
7. [后台管理最小方案](D:/dev/cmr-mini/backend/docs/后台管理最小方案.md)
8. [前后端联调清单](D:/dev/cmr-mini/backend/docs/前后端联调清单.md)
9. [TodoList](D:/dev/cmr-mini/backend/docs/todolist.md)
10. [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)
## 当前系统范围
@@ -58,3 +59,4 @@
- 路由注册：[router.go](D:/dev/cmr-mini/backend/internal/httpapi/router.go)
- migration：[migrations](D:/dev/cmr-mini/backend/migrations)

21
backend/docs/todolist.md
View File

@@ -1,6 +1,6 @@
# Backend TodoList
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 目标
@@ -53,11 +53,11 @@
- `channelCode = mini-demo`
- `channelType = wechat_mini`
## 3. P0 必做
## 3. P0 已完成
## 3.0 固定 session 状态语义
需要 backend 明确并固定：
当前 backend 已明确并固定：
- `finished`
- `failed`
@@ -76,8 +76,6 @@
## 3.1 明确“放弃恢复”的后端处理
这是当前最值得后端配合确认的一点。
当前小程序本地恢复逻辑已经是：
- 进入程序检测到未正常结束对局
@@ -86,11 +84,11 @@
现在本地“放弃”只会清除本地恢复快照。
backend 需要确认的目标语义是：
backend 已确认的目标语义是：
> 玩家点击“放弃恢复”后，这一局是否应同时在业务后端标记为 `cancelled`。
我建议 backend 采用：
当前结论：
- **是，应标记为 `cancelled`**
@@ -100,7 +98,7 @@ backend 需要确认的目标语义是：
- `/events/{id}/play` 和 `/me/entry-home` 可能一直把它当成可继续的局
- 会和小程序本地“已放弃”产生语义分叉
建议 backend 配合确认：
当前 backend 已收口：
1. `POST /sessions/{id}/finish` 使用 `status=cancelled` 是否就是官方放弃语义
2. 如果客户端持有旧 `sessionToken`，恢复放弃时是否允许直接调用 `finish(cancelled)`
@@ -108,7 +106,7 @@ backend 需要确认的目标语义是：
备注：
- 如果 backend 认可这套语义，小程序侧下一步就可以把“点击放弃恢复”改成同步调用 `finish(cancelled)`。
- 小程序侧现在可以把“点击放弃恢复”正式接成同步调用 `finish(cancelled)`。
## 3.2 保证 start / finish 幂等与重复调用安全
@@ -119,12 +117,12 @@ backend 需要确认的目标语义是：
- 故障恢复后二次补报
- 用户重复点击
backend 需要确认：
当前 backend 已确认：
- `start` 重复调用的幂等语义
- `finish` 重复调用的幂等语义
建议：
当前实现：
- `start`：如果已 `running`，返回当前 session，视为成功
- `finish`：如果已进入终态，返回当前 session/result，视为成功
@@ -334,3 +332,4 @@ backend 现在最值得先做的，不是扩接口，而是先确认下面 3 条
> 先把 session 运行态语义、放弃恢复语义和 ongoing session 口径定稳，再继续扩后台配置系统。

3
backend/docs/前后端联调清单.md
View File

@@ -1,6 +1,6 @@
# 前后端联调清单
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 目的
@@ -371,3 +371,4 @@ backend 文档里也规划了：
> backend 业务后端主链已经进入可联调阶段；小程序地图运行内核也已经具备承接能力；下一步最值钱的是补小程序业务 API 层和 launch/finish 两个适配器。

327
backend/docs/后台管理最小方案.md Normal file
View File

@@ -0,0 +1,327 @@
# 后台管理最小方案
> 文档版本：v1.0
> 最后更新：2026-04-02 09:01:17
## 1. 目标
后台第一版不是做一个“大而全配置表单”，而是先做一套最小可运营壳，解决这 3 个问题：
1. 共享资源能被对象化管理
2. `event` 能引用这些资源并组装配置
3. 能从 source -> build -> release 完成发布
一句话：
> 后台第一版管理的是“资源对象 + 引用关系 + 发布流程”，不是“直接编辑一个越来越大的 JSON 文件”。
## 2. 设计边界
### 2.1 后台应该管理什么
- 地图对象
- 赛场 / KML 对象
- 资源包对象
- Event 基础信息
- Event 对资源对象的引用
- Build / Release 发布记录
### 2.2 后台不应该一开始就做什么
- 把所有配置项做成一个超大表单
- 把玩家运行时设置也塞进发布配置
- 把前端运行时编译逻辑搬到后端后台
- 直接按 `event` 管理所有资源文件
### 2.3 与未来 APP 的关系
后台配置不是“小程序后台”，而是统一配置运营后台。
所以第一版开始就要坚持：
- 资源对象平台级复用
- `release / manifest` 终端中立
- 同一份发布结果同时服务小程序和未来 APP
## 3. 第一版建议模块
### 3.1 地图管理
作用：
- 管理可复用地图对象和版本
建议字段：
- 地图名称
- 地图编码
- 版本号
- `mapmeta` 文件
- 瓦片根路径
- 覆盖范围
- 状态
- 备注
第一版动作：
- 新建地图
- 新建地图版本
- 查看地图版本详情
- 停用某个版本
### 3.2 赛场 / KML 管理
作用：
- 把 KML / GeoJSON / 控制点数据做成独立可复用对象
建议字段：
- 赛场名称
- 赛场编码
- 版本号
- 原始文件
- 控制点数量
- 边界摘要
- 状态
- 备注
第一版动作：
- 上传 KML
- 新建赛场版本
- 查看赛场版本详情
- 停用某个版本
### 3.3 资源包管理
作用：
- 管理内容页、音频、主题等共享资源
建议字段：
- 资源包名称
- 资源包编码
- 版本号
- 内容页入口
- 音频包入口
- 主题配置入口
- 状态
- 备注
第一版动作：
- 新建资源包
- 新建资源包版本
- 查看资源包版本详情
### 3.4 Event 组装
作用：
- 管理业务活动本身，并引用共享资源对象
建议字段：
- Event 名称
- Event 编码 / public id
- 简介
- 状态
- 当前选用地图版本
- 当前选用赛场版本
- 当前选用资源包版本
- 当前玩法模式
- 少量覆盖项
第一版只开放少量覆盖项：
- 标题
- 摘要
- 路线编码
- 玩法模式
- 少量规则开关
不要第一版就开放：
- 全量 `presentation.*`
- 全量 `telemetry.*`
- 全量 `debug.*`
### 3.5 Build / Release 管理
作用：
- 把 source config 变成 preview build，再发布成正式 release
页面需要看到：
- source 列表
- build 列表
- build 状态
- release 列表
- 当前生效 release
- 发布人
- 发布时间
第一版动作：
- 从 source 生成 build
- 查看 build 产物
- 发布 build
- 回滚当前 release
## 4. 后台第一版页面建议
按最小闭环，建议先做 6 个页面：
1. 地图列表页
2. 赛场 / KML 列表页
3. 资源包列表页
4. Event 列表与编辑页
5. Build / Release 列表页
6. 发布详情页
这 6 页够把“资源录入 -> Event 组装 -> 发布 -> launch”跑通。
## 5. 对象模型建议
后台第一版建议围绕这些对象展开：
- `Map`
- `MapVersion`
- `Playfield`
- `PlayfieldVersion`
- `ResourcePack`
- `ResourcePackVersion`
- `Event`
- `EventConfigSource`
- `EventConfigBuild`
- `EventRelease`
关键原则：
- 共享资源按对象库管理
- `event` 只做引用和少量覆盖
- `release` 固化具体版本引用
## 6. 一条完整后台工作流
```mermaid
flowchart LR
A["录入地图版本"] --> D["Event 选择地图版本"]
B["录入赛场版本"] --> D
C["录入资源包版本"] --> D
D --> E["保存 Source Config"]
E --> F["生成 Preview Build"]
F --> G["检查 Manifest / Asset Index"]
G --> H["发布 Release"]
H --> I["前台 Launch 使用新 Release"]
```
## 7. 第一版后端接口需求
后台真正开做前，后端最好先补齐下面这批接口：
### 7.1 地图对象
- `GET /admin/maps`
- `POST /admin/maps`
- `GET /admin/maps/{id}`
- `POST /admin/maps/{id}/versions`
### 7.2 赛场对象
- `GET /admin/playfields`
- `POST /admin/playfields`
- `GET /admin/playfields/{id}`
- `POST /admin/playfields/{id}/versions`
### 7.3 资源包对象
- `GET /admin/resource-packs`
- `POST /admin/resource-packs`
- `GET /admin/resource-packs/{id}`
- `POST /admin/resource-packs/{id}/versions`
### 7.4 Event 组装
- `GET /admin/events`
- `POST /admin/events`
- `GET /admin/events/{id}`
- `PUT /admin/events/{id}`
- `POST /admin/events/{id}/source`
当前状态：
- 已实现
- 当前 `source` 组装方式是：
- 选择 `map version`
- 选择 `playfield version`
- 可选选择 `resource pack version`
- 传 `gameModeCode`
- 可传少量 `overrides`
- backend 直接生成一版可进入现有 build 流程的 source config
### 7.5 Build / Release
- `GET /admin/events/{id}/sources`
- `POST /admin/sources/{id}/build`
- `GET /admin/builds/{id}`
- `POST /admin/builds/{id}/publish`
- `POST /admin/events/{id}/rollback`
当前状态：
- 已实现
- 当前已可用：
- `GET /admin/events/{eventPublicID}/pipeline`
- `POST /admin/sources/{sourceID}/build`
- `GET /admin/builds/{buildID}`
- `POST /admin/builds/{buildID}/publish`
- `POST /admin/events/{eventPublicID}/rollback`
- 当前 rollback 方式：
- 显式传 `releaseId`
- 只允许切回同一 event 下的已发布 release
## 8. 第一版不要做的事
为了避免项目被后台表单拖死，第一版明确不做：
- 全量 schema 可视化编辑器
- 拖拽式配置搭建器
- 复杂权限系统
- 资源批量编排器
- 多层审批流
这些都应该等“最小配置运营闭环”跑通后再说。
## 9. 建议开发顺序
建议按下面顺序推进：
1. 先补资源对象模型和接口
2. 再补 Event 引用组装接口
3. 再补 Build / Release 运营接口
4. 最后再做后台页面
原因：
- 没有稳定后端对象模型，后台页面会反复推翻
- 先把对象和发布链条定住，前后端才不会互相拖拽
当前进度：
1. 资源对象模型和 `/admin/maps`、`/admin/playfields`、`/admin/resource-packs` 已完成
2. `Event` 组装接口 `/admin/events`、`/admin/events/{id}/source` 已完成
3. `pipeline/build/publish` 后台聚合接口已完成
4. `rollback` 已完成
5. 下一步是把这批接口接进 workbench 或正式后台页面
## 10. 一句话结论
是的，后面需要一版后台管理界面。
但第一版不应该是“配置大全编辑器”，而应该是：
> 共享资源管理 + Event 组装 + Build / Release 发布 的最小运营后台。

3
backend/docs/开发说明.md
View File

@@ -1,6 +1,6 @@
# 开发说明
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 环境变量
@@ -196,3 +196,4 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
不要跳回去把玩法规则塞进 backend。

347
backend/docs/接口清单.md
View File

@@ -1,6 +1,6 @@
# API 清单
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 09:01:17
本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -238,6 +238,13 @@
- 将 session 从 `launched` 推进到 `running`
补充约束：
- 幂等
- 重复调用时：
- `launched` 会推进到 `running`
- `running` 或已终态直接返回当前 session
### `POST /sessions/{sessionPublicID}/finish`
鉴权：
@@ -249,6 +256,19 @@
- 结束一局
- 同时沉淀结果摘要
当前结束语义：
- `finished`：正常完成
- `failed`：超时或规则失败
- `cancelled`：主动退出或放弃恢复
补充约束：
- 幂等
- 已终态重复调用直接返回当前 session / result
- `finish(cancelled)` 是当前“放弃恢复”的官方后端语义
- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
请求体重点：
- `sessionToken`
@@ -427,3 +447,328 @@
- `release.manifestUrl`
- `release.configLabel`
## 9. Admin 资源对象
说明：
- 当前是后台第一版的最小对象接口
- 先只做 Bearer 鉴权
- 暂未接正式 RBAC / 管理员权限模型
### `GET /admin/maps`
鉴权：
- Bearer token
用途：
- 获取地图对象列表
### `POST /admin/maps`
鉴权：
- Bearer token
用途：
- 新建地图对象
请求体重点：
- `code`
- `name`
- `status`
- `description`
### `GET /admin/maps/{mapPublicID}`
鉴权：
- Bearer token
用途：
- 获取地图对象详情和版本列表
### `POST /admin/maps/{mapPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建地图版本
请求体重点：
- `versionCode`
- `mapmetaUrl`
- `tilesRootUrl`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`
### `GET /admin/playfields`
鉴权：
- Bearer token
用途：
- 获取赛场 / KML 对象列表
### `POST /admin/playfields`
鉴权：
- Bearer token
用途：
- 新建赛场对象
请求体重点：
- `code`
- `name`
- `kind`
- `status`
- `description`
### `GET /admin/playfields/{playfieldPublicID}`
鉴权：
- Bearer token
用途：
- 获取赛场对象详情和版本列表
### `POST /admin/playfields/{playfieldPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建赛场版本
请求体重点：
- `versionCode`
- `sourceType`
- `sourceUrl`
- `controlCount`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`
### `GET /admin/resource-packs`
鉴权：
- Bearer token
用途：
- 获取资源包对象列表
### `POST /admin/resource-packs`
鉴权：
- Bearer token
用途：
- 新建资源包对象
请求体重点：
- `code`
- `name`
- `status`
- `description`
### `GET /admin/resource-packs/{resourcePackPublicID}`
鉴权：
- Bearer token
用途：
- 获取资源包对象详情和版本列表
### `POST /admin/resource-packs/{resourcePackPublicID}/versions`
鉴权：
- Bearer token
用途：
- 新建资源包版本
请求体重点：
- `versionCode`
- `contentEntryUrl`
- `audioRootUrl`
- `themeProfileCode`
- `status`
- `publishedAssetRoot`
- `metadata`
- `setAsCurrent`
### `GET /admin/events`
鉴权：
- Bearer token
用途：
- 获取后台 Event 列表
### `POST /admin/events`
鉴权：
- Bearer token
用途：
- 新建后台 Event
请求体重点：
- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`
### `GET /admin/events/{eventPublicID}`
鉴权：
- Bearer token
用途：
- 获取后台 Event 详情
- 返回最新 source config 摘要
### `PUT /admin/events/{eventPublicID}`
鉴权：
- Bearer token
用途：
- 更新 Event 基础信息
请求体重点：
- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`
### `POST /admin/events/{eventPublicID}/source`
鉴权：
- Bearer token
用途：
- 用地图版本、赛场版本、资源包版本组装一版 source config
- 直接落到现有 `event_config_sources`
请求体重点：
- `map.mapId`
- `map.versionId`
- `playfield.playfieldId`
- `playfield.versionId`
- `resourcePack.resourcePackId`
- `resourcePack.versionId`
- `gameModeCode`
- `routeCode`
- `overrides`
- `notes`
### `GET /admin/events/{eventPublicID}/pipeline`
鉴权：
- Bearer token
用途：
- 从后台视角聚合查看某个 event 的：
- sources
- builds
- releases
- current release
### `POST /admin/sources/{sourceID}/build`
鉴权：
- Bearer token
用途：
- 基于某个 source 生成 preview build
### `GET /admin/builds/{buildID}`
鉴权：
- Bearer token
用途：
- 查看某次 build 详情
### `POST /admin/builds/{buildID}/publish`
鉴权：
- Bearer token
用途：
- 将某次成功 build 发布成正式 release
- 自动切换 event 当前 release
### `POST /admin/events/{eventPublicID}/rollback`
鉴权：
- Bearer token
用途：
- 将 event 当前 release 显式切回某个已发布 release
请求体重点：
- `releaseId`

33
backend/docs/数据模型.md
View File

@@ -1,9 +1,9 @@
# 数据模型
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
当前 migration 共 5 版。
当前 migration 共 6 版。
## 1. 迁移清单
@@ -12,6 +12,7 @@
- [0003_home.sql](D:/dev/cmr-mini/backend/migrations/0003_home.sql)
- [0004_results.sql](D:/dev/cmr-mini/backend/migrations/0004_results.sql)
- [0005_config_pipeline.sql](D:/dev/cmr-mini/backend/migrations/0005_config_pipeline.sql)
- [0006_resource_objects.sql](D:/dev/cmr-mini/backend/migrations/0006_resource_objects.sql)
## 2. 表分组
@@ -98,6 +99,21 @@
- 保存构建后的 manifest 和 asset index
- 保存正式 release 关联的资产清单
### 2.7 共享资源对象
- `maps`
- `map_versions`
- `playfields`
- `playfield_versions`
- `resource_packs`
- `resource_pack_versions`
职责：
- 把地图、KML/赛场、内容资源包做成可复用对象
- 支撑后台第一版按“资源对象 + 版本”管理
- 给后续 event 引用组装和发布流程提供稳定边界
## 3. 当前最关键的关系
### `tenant -> entry_channel`
@@ -132,6 +148,18 @@
- build 是构建态
- release 是发布态
### `map -> map_version`
一张地图可有多个版本。
### `playfield -> playfield_version`
一份赛场/KML 可有多个版本。
### `resource_pack -> resource_pack_version`
一套内容/音频/主题资源可有多个版本。
## 4. 当前已落库但仍应注意的边界
### 4.1 不要把玩法细节塞回事件主表
@@ -173,3 +201,4 @@
这些后面要按真正业务需要补 migration，不要先拍脑袋建大而全表。

26
backend/docs/核心流程.md
View File

@@ -1,6 +1,6 @@
# 核心流程
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 总流程
@@ -182,6 +182,29 @@ APP 当前主链是手机号验证码：
这保证了业务登录态和一局游戏运行态是分开的。
### 7.3 当前状态语义
- `launched`：已创建一局，客户端尚未正式开始
- `running`：客户端已开始本局
- `finished`：正常完成
- `failed`：超时或规则失败
- `cancelled`：主动退出或放弃恢复
补充约束：
- `cancelled` 和 `failed` 都不再作为 ongoing session 返回
- “放弃恢复”当前正式收口为 `finish(cancelled)`
- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
### 7.4 幂等要求
- `start` 幂等：
- `launched` -> `running`
- 重复 `start` 不应报错
- `finish` 幂等：
- 第一次进入终态后，重复 `finish` 直接返回当前结果
- 这个约束同时服务小程序故障恢复和未来 APP 重试补报
## 8. 结果流程
### 8.1 当前接口
@@ -230,3 +253,4 @@ APP 当前主链是手机号验证码：
业务接口必须保持统一，终端差异只进入上下文，不进入对象模型分叉。

3
backend/docs/系统架构.md
View File

@@ -1,6 +1,6 @@
# 系统架构
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 目标
@@ -235,3 +235,4 @@
不要把微信身份或业务 token 直接暴露给实时网关。

3
backend/docs/资源对象与目录方案.md
View File

@@ -1,6 +1,6 @@
# 资源对象与目录方案
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
本文档用于把“地图复用、KML 复用、内容资源复用、配置发布”统一收成一套后端可执行方案。
@@ -591,3 +591,4 @@ gotomars/event-releases/{eventPublicID}/{releasePublicID}/asset-index.json
并且这套模型必须从一开始就兼顾未来 APP，而不是做成“小程序跑通后再重构”的临时结构。

3
backend/docs/配置管理方案.md
View File

@@ -1,6 +1,6 @@
# 配置管理方案
> 文档版本：v1.0
> 最后更新：2026-04-02
> 最后更新：2026-04-02 08:28:05
## 1. 目标
@@ -414,3 +414,4 @@
这样以后无论你配置项怎么继续长，主架构都还能撑住。