完善活动运营域与联调标准化

doc/backend/生产发布与数据库上线方案.md

@@ -0,0 +1,208 @@
+# 生产发布与数据库上线方案
+> 文档版本：v1.0
+> 最后更新：2026-04-03 16:20:00
+
+## 1. 目标
+
+本文档用于约定：
+
+- 开发测试数据库与正式生产数据库的关系
+- 正式上线时数据库如何初始化与升级
+- 后端服务如何与数据库发布配合
+- 每次上线前后的最小检查项
+
+当前原则只有一条：
+
+- **测试库继续做测试，生产库独立建库，靠 migration 升级，不靠手工拷贝。**
+
+---
+
+## 2. 环境划分
+
+建议至少分 2 套数据库环境：
+
+- `dev`：开发 / 联调 / demo / workbench
+- `prod`：正式生产
+
+如果条件允许，推荐分 3 套：
+
+- `dev`
+- `staging`
+- `prod`
+
+其中：
+
+- `dev` 用于日常开发和联调
+- `staging` 用于上线前预演
+- `prod` 只承载正式业务数据
+
+---
+
+## 3. 当前数据库结构来源
+
+当前仓库已经采用 migration 驱动结构演进，目录位于：
+
+- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations)
+
+当前已存在的迁移文件包括：
+
+- `0001_init.sql`
+- `0002_launch.sql`
+- `0003_home.sql`
+- `0004_results.sql`
+- `0005_config_pipeline.sql`
+- `0006_resource_objects.sql`
+- `0007_variant_minimal.sql`
+- `0008_production_skeleton.sql`
+- `0009_event_ops_phase2.sql`
+
+因此正式上线时，数据库结构应以这些 migration 为准，而不是以当前测试库的现状为准。
+
+---
+
+## 4. 第一次生产上线
+
+第一次正式上线建议按以下顺序执行：
+
+1. 新建生产 PostgreSQL 数据库
+2. 配置生产环境变量
+3. 按顺序执行全部 migration
+4. 导入必要的生产基础数据
+5. 部署后端服务
+6. 执行最小 smoke test
+7. 再切前端 / 小程序到生产后端
+
+### 4.1 生产环境变量
+
+至少应与开发环境分离以下配置：
+
+- `DATABASE_URL`
+- JWT 相关密钥
+- 微信小程序相关配置
+- OSS / 资源发布相关配置
+- 其它第三方服务配置
+
+开发环境中的 `.env` 不能直接视为生产配置。
+
+参考文件：
+
+- [D:\dev\cmr-mini\backend\.env.example](D:/dev/cmr-mini/backend/.env.example)
+
+### 4.2 生产初始数据
+
+第一次上线时，建议只导入最小必要数据，例如：
+
+- 租户
+- 默认渠道
+- 最小活动与地图运行数据
+
+不建议把开发联调用的 demo 数据直接原样导入生产。
+
+---
+
+## 5. 后续版本上线
+
+每次后续正式上线建议固定为以下顺序：
+
+1. 备份生产数据库
+2. 部署前确认本次新增 migration
+3. 执行新增 migration
+4. 发布后端服务
+5. 验证关键接口
+6. 再切客户端或前端流量
+
+关键接口最少应验证：
+
+- 登录
+- 活动列表
+- 活动详情
+- `launch`
+- `session start / finish`
+- `result / history`
+
+---
+
+## 6. 上线原则
+
+### 6.1 不直接复用测试库
+
+禁止做法：
+
+- 直接把开发测试数据库改名当生产库
+- 通过手工拷表来“上线”
+- 在生产库中临时手改结构但不补 migration
+
+### 6.2 结构变更只走 migration
+
+所有数据库结构变化都应：
+
+- 新增 migration 文件
+- 进入版本管理
+- 随代码一起发布
+
+不应依赖口头约定或临时 SQL。
+
+### 6.3 生产数据与测试数据分离
+
+开发 demo 数据、联调活动、手工实验数据，应停留在：
+
+- `dev`
+- 或 `staging`
+
+不要直接进入 `prod`。
+
+### 6.4 代码版本与数据库版本对应
+
+每次上线都应能回答两件事：
+
+- 当前代码对应到哪一个 migration 版本
+- 当前生产库已经执行到哪一个 migration 版本
+
+---
+
+## 7. 推荐的发布节奏
+
+建议发布节奏为：
+
+### 阶段 1：数据库先行
+
+- 新 migration 先在 `dev` 验证
+- 再在 `staging` 演练
+- 最后进入 `prod`
+
+### 阶段 2：服务发布
+
+- 后端服务发布到对应环境
+- 验证启动、连接数据库、关键接口可用
+
+### 阶段 3：客户端切换
+
+- 小程序 / App / H5 再切到新的后端能力
+- 避免客户端先切到一个数据库未升级的后端版本
+
+---
+
+## 8. 当前项目建议的最小上线清单
+
+对当前仓库，正式上线前建议至少确认：
+
+- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations) 已完整纳入发布
+- [D:\dev\cmr-mini\doc\backend\后台生产闭环架构草案.md](D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md) 中当前主线对象已落库
+- `DATABASE_URL` 已切到生产库
+- JWT / 微信 / OSS 配置已替换为生产值
+- workbench / 管理接口在生产环境默认不对外暴露或受限
+- demo 事件、demo variant 不进入生产正式运营入口
+
+---
+
+## 9. 一句话结论
+
+当前项目的正式上线方式应固定为：
+
+- **新建独立生产库**
+- **通过 migration 初始化和升级**
+- **通过生产环境变量部署后端**
+- **通过最小 smoke test 验证**
+- **最后再切客户端入口**
+
+不要把开发测试数据库直接视为生产数据库。