Trang chủ Khám phá Trợ giúp
Đăng nhập
zhangyan
/
mini-prog
1
0
Fork 0
Các tập tin Các vấn đề 0 Yêu cầu khéo về 0 Wiki
Tree: 6cd16f08dd
Branches Tags
mini-prog
/
backend
zhangyan 6cd16f08dd 推进活动系统最小成品闭环与游客体验 15 giờ trước cách đây
..
cmd 94a1f0ba78 Add backend foundation and config-driven workbench 6 ngày trước cách đây
docs 6cd16f08dd 推进活动系统最小成品闭环与游客体验 15 giờ trước cách đây
internal 6cd16f08dd 推进活动系统最小成品闭环与游客体验 15 giờ trước cách đây
migrations 6cd16f08dd 推进活动系统最小成品闭环与游客体验 15 giờ trước cách đây
scripts 0e28f70bad 完善多赛道联调与全局产品架构 5 ngày trước cách đây
.env.example a70dc8d5d0 完善后端联调链路与模拟器多通道支持 6 ngày trước cách đây
README.md 6cd16f08dd 推进活动系统最小成品闭环与游客体验 15 giờ trước cách đây
go.mod 94a1f0ba78 Add backend foundation and config-driven workbench 6 ngày trước cách đây
go.sum 94a1f0ba78 Add backend foundation and config-driven workbench 6 ngày trước cách đây
start-backend.ps1 0e28f70bad 完善多赛道联调与全局产品架构 5 ngày trước cách đây

README.md

Backend

文档版本：v1.41 最后更新：2026-04-07 18:15:01

这套后端现在已经能支撑一条完整主链：

entry -> auth -> home/cards -> event play -> launch -> session -> result

当前已实现接口总数：

  • 116

开发环境补充说明：

  • /admin/ops-workbench 与 /ops/admin/* 在 APP_ENV != production 时默认免登录可用。
  • 即使浏览器里残留旧的玩家 token、过期 token 或非 ops token，运维链也会自动回退到 dev ops 上下文。
  • 生产环境不变，仍然必须使用正式 ops token。
  • 运维后台当前采用“左侧流程导航 + 中间单主视图 + 右侧状态/日志”结构，不再把地图、路线、活动、发布动作平铺在一个长页面里。
  • 资源总览 先展示关键统计与当前运行时信息；地图页只保留关联活动数量和摘要，活动明细统一放到 活动管理 / 活动编排。
  • 地图 / 地点管理 当前按“地图列表优先”组织：
    • 先看地图列表
    • 右上角只放 添加地图 / 添加地点
    • 地点编辑区改成省/市两级选择
    • 一张地图只属于一个地点，一个地点可挂多张地图

新增的游客模式公开接口：

  • GET /public/experience-maps
  • GET /public/experience-maps/{mapAssetPublicID}
  • GET /public/events/{eventPublicID}
  • GET /public/events/{eventPublicID}/play
  • POST /public/events/{eventPublicID}/launch

这组接口用于支撑“未登录游客只体验默认活动”的最小链路。

新增的地图资源与默认体验活动接口：

  • GET /experience-maps
  • GET /experience-maps/{mapAssetPublicID}

这组接口用于支撑“地图列表下的默认活动”最小产品化需求。

新增的运维地图管理接口：

  • GET /ops/admin/region-options
  • GET /admin/map-assets
  • PUT /admin/map-assets/{mapAssetPublicID}
  • GET /ops/admin/map-assets
  • PUT /ops/admin/map-assets/{mapAssetPublicID}
  • GET /ops/admin/course-sources
  • GET /ops/admin/course-sources/{sourcePublicID}
  • GET /ops/admin/course-sets/{courseSetPublicID}
  • POST /ops/admin/events
  • PUT /ops/admin/events/{eventPublicID}

这组接口用于把运维后台收成统一主流程：

  • 地图管理：列表 / 新增 / 编辑 / 详情 / 关联活动
  • KML / 赛道管理：围绕当前地图查看赛道集和默认路线
  • 活动管理：列表 / 新增 / 修改 / 详情 / 默认绑定 / 发布
  • 运维后台 UI 当前也已按“左侧导航 + 单主视图 + 右侧常驻状态栏”收口，不再把所有功能平铺在一个长页面里
  • 主区当前已改成宽屏自适应，不再固定窄宽度浪费屏幕空间

并且已经按“配置驱动游戏”收口：

  • 业务对象是 event
  • 运行配置对象是 event_release
  • 真正进入游戏时客户端消费的是 manifest_url
  • session 会固化当时实际绑定的 release

当前还要明确一条业务规则：

  • 玩家进入游戏，必须基于“已发布 release”
  • event 默认绑定、活动草稿配置、未发布 presentation / content bundle 都不能直接作为玩家正式进入依据
  • 当前 currentPresentation / currentContentBundle 在玩家链路里表示的是：
    • 当前已发布 release 实际绑定的展示版本摘要
    • 当前已发布 release 实际绑定的内容包摘要
  • 它们不是 event 草稿默认值摘要
  • 当前 play.canLaunch 和 launch 也已按同一套规则收口：
    • 只有当当前发布 release 同时具备：
    • manifest
    • runtime
    • presentation
    • content bundle 时，玩家才允许正式进入
  • 游客模式当前只允许进入：
    • is_default_experience = true 的活动
    • 且必须基于当前已发布 release
  • 游客模式当前不开放：
    • /me/entry-home
    • /me/results
    • 用户历史成绩与报名态
  • 游客模式 launch 会复用正式 session 模型，但返回：
    • launch.source = public-default-experience
    • launch.business.isGuest = true

当前 workbench 里新增的“当前 Launch 实际配置摘要”仅用于调试：

  • 它会由 backend 代读当前 launch 对应的 manifest
  • 用来显示：
    • configUrl
    • releaseId
    • manifestUrl
    • schemaVersion
    • playfield.kind
    • game.mode
  • 这块只服务联调排查，不参与正式客户端运行链路
  • 正式客户端仍应直接消费 launch 返回的：
    • launch.config.configUrl
    • launch.resolvedRelease.manifestUrl

当前 workbench 里新增的“前端调试日志”也仅用于联调：

  • frontend 可将页面侧调试日志 POST 到 /dev/client-logs
  • backend 会临时保留最近 200 条日志，供 workbench 查看与清空
  • 这块只用于联调排查，不替代正式生产日志体系

当前 demo 真实输入第一刀也已经接入：

  • workbench 的玩法切换会自动填入 backend 内置的：
    • game manifest
    • presentation schema
    • content manifest
  • 这些 demo 资源通过 backend 提供的 dev 路由读取：
    • GET /dev/demo-assets/manifests/{demoKey}
    • GET /dev/demo-assets/presentations/{demoKey}
    • GET /dev/demo-assets/content-manifests/{demoKey}

当前 workbench 的 Bootstrap 语义也已经拆开：

  • Bootstrap Demo（只准备数据）
    • 只准备 demo 测试数据和基础已发布态，不额外重新发布当前玩法
  • Bootstrap + 发布当前玩法
    • 先准备 demo，再对当前选中的玩法执行一遍“发布活动配置（自动补 Runtime）”
  • 这两条路由只服务联调，不进入正式客户端发布链
  • 当前三条标准 demo 在 Bootstrap Demo（只准备数据） 后都会直接具备：
    • 当前 release
    • runtime
    • presentation
    • content bundle
  • 也就是说，frontend 当前从首页选顺序赛、积分赛、多赛道时，已经可以直接走“当前已发布 release”语义联调入口、详情和 canLaunch
  • 当前联调样例文案也已从 Demo ... 收口为中文活动样例，便于前端和总控直接对口排查
  • 当前 manual 多赛道 demo 也已切到 4 条正式 OSS KML：
    • gotomars/kml/lxcb-001/2026-04-07/route01.kml
    • gotomars/kml/lxcb-001/2026-04-07/route02.kml
    • gotomars/kml/lxcb-001/2026-04-07/route03.kml
    • gotomars/kml/lxcb-001/2026-04-07/route04.kml
  • 资源目录约束同步明确：
    • 正式资源目录只认 OSS / CDN
    • 本地 tmp/ 仅作为临时收件箱，不参与正式发布源
  • 当前运维入口第一期已开始落地，先开放两条最小录入链：
    • POST /admin/ops/tile-releases/import
    • POST /admin/ops/course-sets/import-kml-batch
  • 当前目标是先把：
    • 地图瓦片版本录入
    • KML 批量录入并组装为 course set / variants 收成可重复执行的运维入口，而不是继续依赖手工脚本或改代码上传 OSS
  • 当前运维入口第二期已起步，开始支持统一资源纳管：
    • GET /admin/assets
    • POST /admin/assets/register-link
    • POST /admin/assets/upload
    • GET /admin/assets/{assetPublicID}
  • 当前边界：
    • 允许“上传文件”与“登记外链”两种录入模式
    • backend 负责 OSS 存储和资源对象登记
    • 运维后台当前开始使用独立鉴权链：
    • /ops/auth/*
    • /ops/admin/*
    • 设计目标：
    • 运维账号与前端玩家账号完全分离
    • 生产环境走手机号验证码注册/登录
    • 后续可扩多租户与角色分级
    • 已新增独立运维入口：
    • GET /admin/ops-workbench
    • 当前开始把“调试后台”和“运维后台”拆开：
    • /dev/workbench 继续只做联调、回归、日志与摘要
    • /admin/ops-workbench 只做资源录入、OSS 纳管、地图/KML 导入
    • 当前开发环境为了录资源和调发布方便，运维后台默认免登录放行：
    • 可直接打开 /admin/ops-workbench
    • 可直接调用 /ops/admin/*
    • 只有主动验证运维账号链路时，才需要使用 /ops/auth/*
    • Import Tile Release / Import KML Batch 当前已从调试工作台主操作区迁到：
    • /admin/ops-workbench
    • /dev/workbench 当前只保留运维后台入口说明与跳转，不再承载正式资源录入操作
    • /admin/ops-workbench 当前已收成 5 块结构：
    • 资源总览
    • 地图资源管理
    • 资源录入
    • 赛道集管理
    • 活动绑定
    • 发布中心
    • 当前地图资源管理第一刀已接进运维后台：
    • 读取地点列表
    • 新建地点
    • 读取地点详情
    • 新建地图资源
    • 读取地图详情
    • 查看当前瓦片版本与默认活动摘要

当前活动卡片列表最小产品化第一刀也已经进入 backend：

  • /cards
  • /home
  • /me/entry-home

这三处当前已统一补齐最小活动卡片摘要字段：

  • summary
  • status
  • statusCode
  • timeWindow
  • ctaText
  • isDefaultExperience
  • eventType
  • currentPresentation
  • currentContentBundle

当前口径：

  • 卡片摘要与详情页继续共用同一套“当前发布 release 摘要”语义
  • currentPresentation / currentContentBundle 仍表示：
    • 当前已发布 release 实际绑定的展示版本摘要
    • 当前已发布 release 实际绑定的内容包摘要
  • isDefaultExperience 当前由卡片显式字段控制
  • timeWindow / ctaText 当前先按后端派生规则提供，允许后续继续演进

当前“准备页地图预览 V1”也已开始接入，但仍保持只读增强项边界：

  • 当前只把预览字段挂在：
    • GET /events/{eventPublicID}
    • GET /events/{eventPublicID}/play
  • 当前新增字段为：
    • preview.mode
    • preview.baseTiles.tileBaseUrl
    • preview.baseTiles.zoom
    • preview.baseTiles.tileSize
    • preview.viewport.width / height
    • preview.viewport.minLon / minLat / maxLon / maxLat
    • preview.variants[].controls
    • preview.variants[].legs
    • preview.selectedVariantId
  • 当前只服务准备页只读地图预览：
    • 不进入正式 launch 主链
    • 不单独造新的地图资源体系
  • 非 demo / 非带预览元数据的活动允许返回空
  • workbench 当前也已新增固定摘要卡：
    • 准备页地图预览状态
    • 用于直接查看当前活动回出的 preview 关键字段

文档导航

快速启动

  1. 配置环境变量，参考 .env.example
  2. 按顺序执行 migrations
  3. 启动服务
cd D:\dev\cmr-mini\backend
.\start-backend.ps1

当前重点

  • 统一登录：短信 + 微信小程序
  • 多入口：tenant + entry_channel
  • 首页聚合：/home、/cards、/me/entry-home
  • 配置驱动启动：/events/{id}/play、/events/{id}/launch
  • 局生命周期：start / finish / detail
  • 局后结果：/sessions/{id}/result、/me/results
  • 第一阶段生产骨架：places / map-assets / tile-releases / course-sources / course-sets / course-variants / runtime-bindings
  • 第三刀最小接线：runtimeBinding -> eventRelease -> launch.runtime
  • 第四刀发布闭环：publish(runtimeBindingId) -> eventRelease -> launch.runtime
  • 活动运营域第二阶段：event_presentations / content_bundles / event_release -> presentation,bundle,runtime
  • 活动运营域第二阶段第二刀：event detail / event play / launch -> presentation,bundle 摘要
  • 活动运营域第二阶段第三刀：release 摘要闭环 + content bundle import
  • 活动运营域第二阶段第四刀：presentation import + event 默认 active 绑定 + publish 默认继承
  • 开发工作台：/dev/workbench
    • 用户主链调试
    • 资源对象与 Event 组装调试
    • Build / Publish / Rollback 调试
    • Release / RuntimeBinding 最小挂接验证
    • Event Presentation / Content Bundle 最小挂接验证
    • Content Bundle Import 最小导入验证
    • Presentation Import / Event 默认绑定 / Publish 默认继承验证
    • Runtime 自动补齐 + 默认绑定发布一键验证
    • Bootstrap Demo 自动回填最小生产骨架 ID
    • 一键测试环境：可从空白状态自动准备 demo event、source/build/release、presentation、content bundle、place、map asset、tile release、course source、course set、course variant、runtime binding，并输出逐步日志与预期判定
    • 一键标准回归：在标准发布链跑通后，继续自动验证 play / launch / result / history
    • 真实输入替换第一刀：Bootstrap Demo 已改用真实可访问的 KML 与地图资源 URL
    • manual 多赛道 demo：已切到真实 c01.kml / c02.kml 输入
    • 前端调试日志：
    • POST /dev/client-logs
    • GET /dev/client-logs
    • DELETE /dev/client-logs
    • 显式玩法入口：
    • 顺序赛：evt_demo_001
    • 积分赛：evt_demo_score_o_001
    • 多赛道：evt_demo_variant_manual_001