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-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
Download Patch File Download Diff File Expand all files Collapse all files

500
b2b.md Normal file
View File

@@ -0,0 +1,500 @@
# B2B 交接文档
> 文档版本：v1.0
> 最后更新：2026-04-07 18:47:09
## 1. 文档用途
这份文档给“新线程 / 新接手人”直接使用，目标是：
1. 快速理解当前 backend 主线已经做到哪里。
2. 明确哪些架构约束已经定死，不能再随意回退。
3. 明确当前运维后台、调试后台、前后端联调各自的边界。
4. 给出下一步应该从哪里继续，而不是重新摸索一遍。
---
## 2. 先说结论
当前 backend 已经形成三条比较稳定的主线：
1. `玩家链`
- `entry -> auth -> home/cards -> event detail/play -> launch -> session -> result`
2. `游客链`
- `public experience maps -> public event detail/play -> public launch`
3. `运维链`
- `资源录入 -> 地图/地点管理 -> 路线资源管理 -> 活动管理/编排 -> 发布中心`
同时，调试与运维已经明确分离：
- 调试后台：`/dev/workbench`
- 运维后台：`/admin/ops-workbench`
当前接口总数：
- `116`
---
## 3. 当前最重要的架构边界
### 3.1 活动运行模型
当前已经明确，第一阶段活动模型按最小运行单元收口：
- `单地图`
- `单路线组`
- `单玩法`
不要在第一阶段把单个活动扩成：
- 多地图
- 多路线组
- 多玩法
复杂需求后续通过两种方式承接：
1. `活动实例化`
- 一个复杂主题拆成多个明确活动实例。
2. `组合入口 / 组合卡片`
- 前台组合多个活动实例形成复杂入口。
这条原则已经同步给总控，后续不要回退。
### 3.2 玩家进入游戏的依据
玩家进入游戏必须基于：
- `已发布 release`
而不是：
- event 草稿
- event 默认绑定
- 未发布的 presentation / content bundle
当前 `play.canLaunch` 已按这条规则收紧：
必须同时具备：
- event 是 `active`
- 当前已发布 release 存在
- release 有 `manifest`
- release 绑定了 `runtime`
- release 绑定了 `presentation`
- release 绑定了 `content bundle`
否则：
- `play.canLaunch = false`
### 3.3 调试后台与运维后台分离
不要再把所有能力塞回一个页面。
当前原则：
- `/dev/workbench`
- 只做联调、一键回归、日志、摘要、问题排查
- `/admin/ops-workbench`
- 只做资源录入、地图/路线/活动管理、发布中心
---
## 4. 用户明确表达过的产品/交互偏好
这些是用户多次强调过的，后续要严格遵守。
### 4.1 不要把所有功能平铺在一个长页面里
用户明确反感“所有功能平铺一个页面”的方式。
正确方向：
- 列表就是列表
- 点某一项进详情
- 新增/编辑用：
- 新页面
- 弹出页
- 分步流程
不要继续堆按钮。
### 4.2 运维后台要符合人的使用习惯
例如在地图管理里，用户明确要求的是：
1. 先进入地图列表
2. 右上角有：
- `添加地图`
- `添加地点`
3. 点一张地图再进入详情
4. 地图上传能力要放在地图管理里
### 4.3 运维后台 UI 必须尽量利用宽屏
用户明确要求：
- 不要再固定窄宽度
- 主区要做最大宽度适配
- 不要浪费屏幕空间
### 4.4 开发环境尽量免登录
用户明确要求：
- 开发环境不要每次都要求登录
当前已实现：
- `APP_ENV != production` 时，`/ops/admin/*` 默认可免登录使用
- 即使浏览器残留旧玩家 token / 过期 token / 非 ops token，也会自动 fallback 到 dev ops 上下文
---
## 5. 当前已完成的关键能力
## 5.1 调试后台
入口：
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\dev_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/dev_handler.go)
地址：
- `/dev/workbench`
已完成：
- demo bootstrap
- 一键发布链
- 一键标准回归
- 前端调试日志上报与查看
- 当前玩法关键状态卡
- Launch 实际配置摘要
- 准备页地图预览状态
- API 目录按业务链分类展示
调试链已经能稳定支撑：
- 选玩法
- 回归
- 看日志
- 看 launch / manifest / preview 摘要
## 5.2 游客模式
公开接口：
- `GET /public/experience-maps`
- `GET /public/experience-maps/{mapAssetPublicID}`
- `GET /public/events/{eventPublicID}`
- `GET /public/events/{eventPublicID}/play`
- `POST /public/events/{eventPublicID}/launch`
语义：
- 只允许默认体验活动
- 只允许基于已发布 release
- `launch.business.isGuest = true`
- `launch.source = public-default-experience`
游客 launch 曾经被 `guest` identity DB 约束卡死，已通过 migration 修复。
## 5.3 地图列表下的默认体验活动
接口：
- `GET /experience-maps`
- `GET /experience-maps/{mapAssetPublicID}`
当前用于前端地图列表下的“默认体验活动”展示。
## 5.4 运维后台
入口：
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\ops_workbench_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/ops_workbench_handler.go)
地址：
- `/admin/ops-workbench`
当前导航结构已收成：
- `资源总览`
- `地图 / 地点管理`
- `路线资源管理`
- `活动管理`
- `活动编排`
- `发布中心`
- `资源录入`
注意：
- 这只是第一版结构
- 还没有完全做成成熟的列表页/详情页后台
- 但已经明确不再走“全平铺”老路
## 5.5 资源录入第二期基础能力
已新增统一资源模型接口：
- `GET /ops/admin/assets`
- `POST /ops/admin/assets/register-link`
- `POST /ops/admin/assets/upload`
- `GET /ops/admin/assets/{assetPublicID}`
目的：
- 运维无需操心资源到底来自上传文件还是外链
- 最终都纳管成统一资源对象
---
## 6. 当前地图/地点管理做到哪里了
这是接下来最可能继续做的主线。
当前已经做了这些：
1. 地图/地点管理已不再是平铺对象区
2. 地图列表成为主入口
3. 右上角只有：
- `添加地图`
- `添加地点`
4. 地图详情改成弹层
5. 地点编辑改成弹层
6. 地点支持：
- 省份
- 城市
- 最终回填 `region`
7. 新增地区接口：
- `GET /ops/admin/region-options`
地区数据源：
- [https://github.com/uiwjs/province-city-china](https://github.com/uiwjs/province-city-china)
- [https://unpkg.com/province-city-china/dist/province.json](https://unpkg.com/province-city-china/dist/province.json)
- [https://unpkg.com/province-city-china/dist/city.json](https://unpkg.com/province-city-china/dist/city.json)
业务约束：
- 一个地点可以有多张地图
- 一张地图只能属于一个地点
刚刚修复过一个关键前端脚本 bug：
- `managed-place-id` 隐藏状态字段在重构时被删掉
- 导致 `refresh-map-area` 前端脚本异常，只打印 `{ error: {} }`
- 现已补回，同时错误日志已展开成：
- `name`
- `message`
- `stack`
- `status/body/url`
---
## 7. 数据库与 migration 重要说明
开发库：
- `cmr20260401`
注意：
- backend 启动脚本不会自动帮你补所有历史 migration
- 之前已经遇到过“代码修了，库没跟上”的问题
开发库里曾手工补过的重要 migration：
1. [D:\dev\cmr-mini\backend\migrations\0012_managed_assets.sql](D:/dev/cmr-mini/backend/migrations/0012_managed_assets.sql)
2. [D:\dev\cmr-mini\backend\migrations\0013_ops_console.sql](D:/dev/cmr-mini/backend/migrations/0013_ops_console.sql)
3. [D:\dev\cmr-mini\backend\migrations\0015_guest_identity.sql](D:/dev/cmr-mini/backend/migrations/0015_guest_identity.sql)
这些都已经在当前开发库应用过。
如果新线程遇到“文档说修了，但接口还是异常”，先查两件事：
1. 当前 API 实例是不是连着 `cmr20260401`
2. 对应 migration 有没有真的进库
---
## 8. 关键文件入口
### 8.1 路由与中间件
- [D:\dev\cmr-mini\backend\internal\httpapi\router.go](D:/dev/cmr-mini/backend/internal/httpapi/router.go)
- [D:\dev\cmr-mini\backend\internal\httpapi\middleware\ops_auth.go](D:/dev/cmr-mini/backend/internal/httpapi/middleware/ops_auth.go)
### 8.2 调试后台
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\dev_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/dev_handler.go)
### 8.3 运维后台
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\ops_workbench_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/ops_workbench_handler.go)
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\region_options_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/region_options_handler.go)
### 8.4 地图默认体验活动 / 游客模式
- [D:\dev\cmr-mini\backend\internal\service\map_experience_service.go](D:/dev/cmr-mini/backend/internal/service/map_experience_service.go)
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\map_experience_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/map_experience_handler.go)
- [D:\dev\cmr-mini\backend\internal\service\public_experience_service.go](D:/dev/cmr-mini/backend/internal/service/public_experience_service.go)
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\public_experience_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/public_experience_handler.go)
### 8.5 运维总览
- [D:\dev\cmr-mini\backend\internal\store\postgres\ops_summary_store.go](D:/dev/cmr-mini/backend/internal/store/postgres/ops_summary_store.go)
- [D:\dev\cmr-mini\backend\internal\service\ops_summary_service.go](D:/dev/cmr-mini/backend/internal/service/ops_summary_service.go)
### 8.6 资源录入 / 受管资源
- [D:\dev\cmr-mini\backend\internal\service\admin_asset_service.go](D:/dev/cmr-mini/backend/internal/service/admin_asset_service.go)
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\admin_asset_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/admin_asset_handler.go)
- [D:\dev\cmr-mini\backend\internal\store\postgres\asset_store.go](D:/dev/cmr-mini/backend/internal/store/postgres/asset_store.go)
---
## 9. 必读文档
新线程建议先看这些，不要一上来就只看代码。
1. [D:\dev\cmr-mini\backend\README.md](D:/dev/cmr-mini/backend/README.md)
2. [D:\dev\cmr-mini\backend\docs\开发说明.md](D:/dev/cmr-mini/backend/docs/开发说明.md)
3. [D:\dev\cmr-mini\backend\docs\后台管理最小方案.md](D:/dev/cmr-mini/backend/docs/后台管理最小方案.md)
4. [D:\dev\cmr-mini\backend\docs\资源对象与目录方案.md](D:/dev/cmr-mini/backend/docs/资源对象与目录方案.md)
5. [D:\dev\cmr-mini\backend\docs\接口清单.md](D:/dev/cmr-mini/backend/docs/接口清单.md)
6. [D:\dev\cmr-mini\b2t.md](D:/dev/cmr-mini/b2t.md)
7. [D:\dev\cmr-mini\b2f.md](D:/dev/cmr-mini/b2f.md)
其中：
- `b2t.md` 看 backend 写给总控的当前结论
- `b2f.md` 看 backend 写给前端的当前联调口径
---
## 10. 当前最值得继续做的事
新线程接手后，建议优先级如下：
### P0：把“地图/地点管理”真正做成列表 -> 详情流
目标：
1. 地图列表作为稳定主入口
2. 地图详情弹层稳定
3. 添加地图/添加地点弹层稳定
4. 地图上传能力放进地图管理流
这里的“上传地图”不是指调试式填 URL，而是最终要收成：
- 上传文件
- 或登记链接
- backend 统一纳管
### P1：把地图详情页做扎实
建议继续补：
- 当前瓦片版本
- 历史瓦片版本
- 简单预览
- 默认体验活动数量
- 关联活动数量
- 跳转到活动管理
注意：
- 地图页只看数量和摘要
- 活动详情不要重新塞回地图页
### P2：后续再做路线资源管理同样的列表 -> 详情流
KML/路线页也应遵守同一原则：
- 列表就是列表
- 点一项进详情
- 上传就是上传
- 不在首页平铺所有对象编辑器
---
## 11. 本线程最后一次真实修复
如果新线程接手后发现：
- 进入 `/admin/ops-workbench`
- 切到“地图 / 地点管理”
- 状态栏显示：
- `失败：refresh-map-area`
- 响应日志里还是：
- `{ "error": {} }`
先确认是否已经是本线程修后的代码版本。
本线程最后一次修复的是：
- 恢复 `managed-place-id` 隐藏状态字段
- 展开运维页前端异常日志
相关文件：
- [D:\dev\cmr-mini\backend\internal\httpapi\handlers\ops_workbench_handler.go](D:/dev/cmr-mini/backend/internal/httpapi/handlers/ops_workbench_handler.go)
---
## 12. 本地验证方式
不要让新线程重复踩坑，直接照这个流程：
1. backend 编译
```powershell
cd D:\dev\cmr-mini\backend
go build ./...
```
2. 启动 backend
```powershell
cd D:\dev\cmr-mini\backend
.\start-backend.ps1
```
3. 浏览器强刷
```text
Ctrl + F5
```
4. 检查两个入口
- 调试后台：
- [http://127.0.0.1:18090/dev/workbench](http://127.0.0.1:18090/dev/workbench)
- 运维后台：
- [http://127.0.0.1:18090/admin/ops-workbench](http://127.0.0.1:18090/admin/ops-workbench)
---
## 13. 一句话交接
当前 backend 已经把：
- 调试后台
- 游客模式
- 默认体验地图接口
- 运维后台第一版骨架
都立起来了。
接下来最该继续的不是扩新对象，而是把：
**地图 / 地点管理 -> 路线资源管理 -> 活动管理 / 编排 -> 发布中心**
这条运维主流程，按“列表 -> 详情 -> 弹层 / 分步”的方式做扎实。