cmr-mini/b2b.md

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

地址：

• /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

地址：

• /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://unpkg.com/province-city-china/dist/province.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
2. D:\dev\cmr-mini\backend\migrations\0013_ops_console.sql
3. 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\middleware\ops_auth.go

8.2 调试后台

• 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\region_options_handler.go

8.4 地图默认体验活动 / 游客模式

• 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\service\public_experience_service.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\service\ops_summary_service.go

8.6 资源录入 / 受管资源

• 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\store\postgres\asset_store.go

---

9. 必读文档

新线程建议先看这些，不要一上来就只看代码。

1. D:\dev\cmr-mini\backend\README.md
2. D:\dev\cmr-mini\backend\docs\开发说明.md
3. D:\dev\cmr-mini\backend\docs\后台管理最小方案.md
4. D:\dev\cmr-mini\backend\docs\资源对象与目录方案.md
5. D:\dev\cmr-mini\backend\docs\接口清单.md
6. D:\dev\cmr-mini\b2t.md
7. 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

---

12. 本地验证方式

不要让新线程重复踩坑，直接照这个流程：

1. backend 编译

cd D:\dev\cmr-mini\backend
go build ./...

2. 启动 backend

cd D:\dev\cmr-mini\backend
.\start-backend.ps1

3. 浏览器强刷

Ctrl + F5

4. 检查两个入口

• 调试后台：
  • http://127.0.0.1:18090/dev/workbench
• 运维后台：
  • http://127.0.0.1:18090/admin/ops-workbench

---

13. 一句话交接

当前 backend 已经把：

• 调试后台
• 游客模式
• 默认体验地图接口
• 运维后台第一版骨架

都立起来了。

接下来最该继续的不是扩新对象，而是把：

地图 / 地点管理 -> 路线资源管理 -> 活动管理 / 编排 -> 发布中心

这条运维主流程，按“列表 -> 详情 -> 弹层 / 分步”的方式做扎实。