mini-prog/backend/docs/开发说明.md

开发说明

文档版本：v1.0 最后更新：2026-04-02 08:28:05

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
go run .\cmd\api

如果你想固定跑开发工作台常用端口 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

3. 当前开发约定

3.1 开发阶段先不用 Redis

当前第一版全部依赖：

• PostgreSQL
• JWT
• refresh token 持久化

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

3.2 开发环境短信

当前默认可走 console provider。

用途：

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

3.3 微信小程序开发态

当前支持 dev- 前缀 code。

适合：

• 后端联调
• workbench 快速验证

3.4 本地配置目录

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

相关环境变量：

• LOCAL_EVENT_DIR
• ASSET_BASE_URL

作用：

• LOCAL_EVENT_DIR 决定本地 source config 从哪里读
• ASSET_BASE_URL 决定 preview build 时如何把相对资源路径归一化成可运行 URL
• ASSET_PUBLIC_BASE_URL 决定 publish 时如何把公开 URL 映射到 OSS 对象 key
• ASSET_BUCKET_ROOT 决定发布对象上传到哪个 bucket 根路径
• OSSUTIL_PATH 和 OSSUTIL_CONFIG_FILE 决定 backend 发布 manifest 时使用哪个 OSS 客户端

4. Migration

当前 migration 文件在 migrations。

执行原则：

1. 按编号顺序执行
2. schema 变更只通过新增 migration 完成
3. 不直接改线上已执行 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 上没有对象”的假成功

并且支持：

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

6. 当前推荐联调顺序

场景一：小程序快速进入

1. bootstrap-demo
2. login/wechat-mini
3. me/entry-home
4. events/{id}/play
5. events/{id}/launch
6. sessions/{id}/start
7. sessions/{id}/finish
8. sessions/{id}/result

场景二：APP 主身份

1. auth/sms/send
2. auth/login/sms
3. me/entry-home
4. launch
5. session
6. result

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

1. login/wechat-mini
2. auth/sms/send with scene=bind_mobile
3. auth/bind/mobile
4. me/profile

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

1. bootstrap-demo
2. dev/events/{eventPublicID}/config-sources/import-local
3. dev/config-builds/preview
4. dev/config-builds/publish
5. events/{id}
6. events/{id}/launch

7. 当前后续开发建议

文档整理完之后，后面建议按这个顺序继续：

1. 抽出更通用的 play context -> launch 模型
2. 补赛事与报名层
3. 补页面配置和白标首页
4. 再考虑实时网关票据

不要跳回去把玩法规则塞进 backend。