Add backend foundation and config-driven workbench

backend/docs/开发说明.md

@@ -0,0 +1,182 @@
+# 开发说明
+
+## 1. 环境变量
+
+参考 [`.env.example`](D:/dev/cmr-mini/backend/.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`
+
+## 2. 本地启动
+
+```powershell
+cd D:\dev\cmr-mini\backend
+go run .\cmd\api
+```
+
+如果你想固定跑开发工作台常用端口 `18090`，直接执行：
+
+```powershell
+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](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](D:/dev/cmr-mini/event) 导入本地配置文件。
+
+相关环境变量：
+
+- `LOCAL_EVENT_DIR`
+- `ASSET_BASE_URL`
+
+作用：
+
+- `LOCAL_EVENT_DIR` 决定本地 source config 从哪里读
+- `ASSET_BASE_URL` 决定 preview build 时如何把相对资源路径归一化成可运行 URL
+
+## 4. Migration
+
+当前 migration 文件在 [migrations](D:/dev/cmr-mini/backend/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
+
+并且支持：
+
+- 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。