# 开发说明
> 文档版本：v1.0
> 最后更新：2026-04-02


## 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`
- `ASSET_PUBLIC_BASE_URL`
- `ASSET_BUCKET_ROOT`
- `OSSUTIL_PATH`
- `OSSUTIL_CONFIG_FILE`

## 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
- `ASSET_PUBLIC_BASE_URL` 决定 publish 时如何把公开 URL 映射到 OSS 对象 key
- `ASSET_BUCKET_ROOT` 决定发布对象上传到哪个 bucket 根路径
- `OSSUTIL_PATH` 和 `OSSUTIL_CONFIG_FILE` 决定 backend 发布 manifest 时使用哪个 OSS 客户端

## 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

补充说明：

- `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。