开发说明

文档版本：v1.14 最后更新：2026-04-03 20:10:25

1. 环境变量

参考 .env.example。

当前最关键的变量：

APP_ENV
HTTP_ADDR
DATABASE_URL
JWT_ACCESS_SECRET
AUTH_SMS_PROVIDER
AUTH_DEV_SMS_CODE
WECHAT_MINI_APP_ID
WECHAT_MINI_APP_SECRET
WECHAT_MINI_DEV_PREFIX
LOCAL_EVENT_DIR
ASSET_BASE_URL
ASSET_PUBLIC_BASE_URL
ASSET_BUCKET_ROOT
OSSUTIL_PATH
OSSUTIL_CONFIG_FILE

2. 本地启动

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

如果你想固定跑开发工作台常用端口 18090，直接执行：

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

默认会设置：

APP_ENV=development
HTTP_ADDR=:18090
DATABASE_URL=postgres://postgres:asdf*123@192.168.100.77:5432/cmr20260401?sslmode=disable
AUTH_SMS_PROVIDER=console
WECHAT_MINI_DEV_PREFIX=dev-

启动后可直接打开：

http://127.0.0.1:18090/dev/workbench

当前 workbench 已覆盖两类调试链：

用户主链：bootstrap -> auth -> entry/home -> event play/launch -> session -> result
后台运营链：maps/playfields/resource-packs -> admin event source -> build -> publish -> rollback
第一阶段生产骨架联调台：places -> map-assets -> tile-releases -> course-sources -> course-sets -> course-variants -> runtime-bindings
第三刀最小接线验证：runtimeBinding -> release -> launch.runtime
第四刀发布闭环验证：runtimeBinding -> publish(runtimeBindingId) -> release -> launch.runtime
活动运营域第二阶段验证：presentation -> content bundle -> publish(presentationId, contentBundleId, runtimeBindingId) -> release
活动运营域第二阶段第二刀验证：event detail / play / launch -> presentation + content bundle 摘要
活动运营域第二阶段第三刀验证：release 摘要闭环 + content bundle import
活动运营域第二阶段第四刀验证：presentation import -> event 默认 active 绑定 -> publish 空参继承
workbench 一键验证增强：一键默认绑定发布 与 一键补齐 Runtime 并发布
/dev/bootstrap-demo 现在也会回填最小生产骨架：place / map asset / tile release / course source / course set / course variant / runtime binding

2.1 当前推荐验证方式

如果目标是验证“从测试数据准备到 release 继承是否完整”，优先使用 workbench 的一键流，而不是手工逐个点按钮。

当前推荐顺序：

Bootstrap Demo
一键补齐 Runtime 并发布
一键标准回归

当前这条一键链会自动完成：

demo event / source / build / release 准备
presentation 导入
content bundle 导入
event 默认 active 绑定保存
最小生产骨架准备：
- place
- map asset
- tile release
- course source
- course set
- course variant
- runtime binding
publish
release 回读校验
play / launch / result / history 回归汇总
demo 活动残留 ongoing session 清理：
- 会把 demo event 下历史遗留的 launched / running session 自动改成 cancelled

当前日志能力：

每一步都会写到“响应日志”
失败时会直接输出：
- 错误消息
- stack
- 最后一次 curl
成功时“预期结果”面板会直接给出：
- Release ID
- Presentation
- Content Bundle
- Runtime Binding
- 判定
成功跑完标准回归后，“回归结果汇总”会直接给出：
- 发布链
- Play
- Launch
- Result
- History
- Session ID
- 总判定

3. 当前开发约定

3.1 开发阶段先不用 Redis

当前第一版全部依赖：

PostgreSQL
JWT
refresh token 持久化

Redis 后面只在需要性能优化、限流或短期票据缓存时再接。

3.2 开发环境短信

当前默认可走 console provider。

用途：

本地联调无需接真实短信供应商

3.3 微信小程序开发态

当前支持 dev- 前缀 code。

适合：

后端联调
workbench 快速验证

3.4 本地配置目录

当前支持从根目录 event 导入本地配置文件。

4. Migration

当前 migration 文件在 migrations。

执行原则：

按编号顺序执行
schema 变更只通过新增 migration 完成
不直接改线上已执行 migration

5. 开发工作台

`POST /dev/bootstrap-demo`

它会保证 demo 数据存在：

tenant_demo
mini-demo
evt_demo_001
rel_demo_001
card_demo_001

`GET /dev/workbench`

这是当前最重要的联调工具。

可以直接测试：

登录
入口解析
首页聚合
event play
第一阶段生产骨架对象
配置导入、preview build、publish build
launch
session start / finish
result
profile

补充说明：

publish build 现在会真实上传 manifest.json 和 asset-index.json 到 OSS
如果上传失败，接口会直接报错，不再出现“数据库里已有 release，但 OSS 上没有对象”的假成功
Save Event Defaults 会把当前 event 的默认 active 绑定写入：
- currentPresentationId
- currentContentBundleId
- currentRuntimeBindingId
之后 Publish Build 如果不显式填写这三项，会优先继承 event 默认 active 绑定

并且支持：

quick flow
scenario 保存/导入/导出
curl 导出
request history

当前第一阶段生产骨架联调台只做：

list
create
detail
binding

明确不做：

正式后台 UI
edit
delete
batch
审核流

活动运营域第二阶段当前也只做最小动作：

list
create
detail
publish 绑定
import

6. 当前推荐联调顺序

场景一：小程序快速进入

bootstrap-demo
login/wechat-mini
me/entry-home
events/{id}/play
events/{id}/launch
sessions/{id}/start
sessions/{id}/finish
sessions/{id}/result

场景二：APP 主身份

auth/sms/send
auth/login/sms
me/entry-home
launch
session
result

场景三：微信轻账号绑定手机号

login/wechat-mini
auth/sms/send with scene=bind_mobile
auth/bind/mobile
me/profile

场景四：配置发布到可启动 release

bootstrap-demo
dev/events/{eventPublicID}/config-sources/import-local
dev/config-builds/preview
dev/config-builds/publish
events/{id}
events/{id}/launch

场景五：第一阶段生产骨架最小闭环

在 /dev/workbench 的 后台运营 模式中，按下面顺序操作：

List Places 或 Create Place
在该 Place 下 Create Map Asset
在该 MapAsset 下 Create Tile Release
Create Course Source
在该 MapAsset 下 Create Course Set
在该 CourseSet 下 Create Variant
Create Runtime Binding

成功后应能拿到这些 ID：

placeId
mapAssetId
tileReleaseId
courseSourceId
courseSetId
courseVariantId
runtimeBindingId

建议第一次联调时用这组最小规则：

Place 先建 1 个
每个 Place 先只建 1 个 MapAsset
每个 MapAsset 先只建 1 个 TileRelease
每个 CourseSet 先只建 1 个默认 CourseVariant
RuntimeBinding 先只绑定当前正在验证的 Event

这条链当前只验证对象关系闭环，不验证：

发布链切换
launch 返回运行对象字段
EventPresentation
ContentBundle

场景六：第三刀最小接线验证

在 /dev/workbench 的 后台运营 模式中，先完成“场景五”，再按下面顺序操作：

Get Pipeline
确认当前 Release ID
填或复用 Runtime Binding ID
Bind Runtime
Get Release
切回 前台联调
对同一个 event 执行 Launch

场景七：活动运营域第二阶段最小闭环

在 /dev/workbench 的 后台运营 模式中，按下面顺序操作：

Get Event
Create Presentation
Create Bundle
Assemble Source
Build Source
在发布区填：
- Runtime Binding ID
- Presentation ID
- Content Bundle ID
Publish Build
Get Release

成功后应能在 release 返回中看到：

runtime
presentation
contentBundle

并且这 3 类绑定当前都已固化到 event_release。

成功后应能看到：

GET /admin/releases/{releasePublicID} 返回 runtime
POST /events/{eventPublicID}/launch 返回 launch.runtime

当前阶段的约束是：

只新增 runtime 字段块
不改旧的：
- resolvedRelease
- business
- variant
release 如果没挂 runtimeBindingId，则 launch.runtime 为空

场景八：活动运营域第二阶段第三刀验证

在 /dev/workbench 的 后台运营 模式中，先完成“场景七”，再按下面顺序操作：

Create Presentation 或直接复用现有 Presentation ID
Import Bundle
Get Bundle
Get Pipeline
Publish Build
Get Release
切回 前台联调
Event Detail
Event Play
Launch

成功后应能同时看到这三组摘要：

release.presentation.templateKey / version
release.contentBundle.bundleType / version
release.runtime.placeId / mapId / tileReleaseId / courseVariantId

同时客户端消费侧应保持一致：

GET /events/{eventPublicID}
GET /events/{eventPublicID}/play
POST /events/{eventPublicID}/launch

当前 Content Bundle Import 只做统一导入入口，不做复杂资源平台：

输入：
- title
- bundleType
- sourceType
- manifestUrl
- version
- assetManifest
输出：
- bundleId
- bundleType
- version
- assetManifest
- status

场景七：第四刀发布闭环验证