From 041856dc8c5bbcbc59fa21580c8fba607cc6b765 Mon Sep 17 00:00:00 2001
From: huang <youdang2000@gmail.com>
Date: Tue, 14 Apr 2026 11:56:50 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E8=BF=81=E7=A7=BB?=
 =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=EF=BC=8Creset=5Fdb.sh=20?=
 =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20000114=20=E5=9F=BA=E7=BA=BF=E6=A3=80?=
 =?UTF-8?q?=E6=9F=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 migrations/README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++
 scripts/reset_db.sh  |  9 ++++++
 2 files changed, 77 insertions(+)
 create mode 100644 migrations/README.md

diff --git a/migrations/README.md b/migrations/README.md
new file mode 100644
index 0000000..9a8872b
--- /dev/null
+++ b/migrations/README.md
@@ -0,0 +1,68 @@
+# 数据库迁移说明
+
+## 当前结构
+
+```
+migrations/
+├── 000114_squash_baseline.up.sql   ← ⚠️ 待创建（见下方说明）
+├── 000114_squash_baseline.down.sql ← ⚠️ 待创建
+├── 000115_init_data.up.sql         ← 初始化数据（轮询配置 + purchase_role 回填）
+├── 000115_init_data.down.sql
+├── 000116_remove_legacy_commission_fields.up.sql  ← 删除废弃分佣字段
+├── 000116_remove_legacy_commission_fields.down.sql
+└── archive/                        ← 已归档的历史迁移（000000~000113）
+```
+
+## ⚠️ 发布前必做：生成 000114 squash 基线
+
+**背景**：历史迁移（000000-000113）已归档，但尚未生成汇总基线文件。
+现有测试环境的表是在 migrate 工具之外创建的，不受影响。
+但全新环境（本地搭建、CI、生产首次部署）必须有 000114 才能通过 `migrate up` 建表。
+
+**执行时机**：正式发布前，确认 schema 已稳定后执行一次。
+
+**步骤**：
+
+1. 安装 PostgreSQL 客户端（若未安装）：
+   ```bash
+   brew install libpq
+   export PATH="/opt/homebrew/opt/libpq/bin:$PATH"
+   ```
+
+2. 生成 schema 基线（仅 DDL，不含数据）：
+   ```bash
+   PGPASSWORD=<密码> pg_dump \
+     --schema-only --no-owner --no-acl \
+     -h <host> -U <user> -d <dbname> \
+     > migrations/000114_squash_baseline.up.sql
+   ```
+
+3. 在生成的 `000114_squash_baseline.up.sql` 头部加上注释（参考其他迁移文件格式）。
+
+4. 创建 `000114_squash_baseline.down.sql`（删除所有表）：
+   ```sql
+   -- 回滚：删除所有业务表（谨慎执行）
+   DROP TABLE IF EXISTS tb_wechat_config CASCADE;
+   DROP TABLE IF EXISTS tb_tag CASCADE;
+   -- ... 其他表（按依赖倒序）
+   ```
+
+5. 找 AI 协助完成 down.sql 和验证步骤（在全新数据库执行 `migrate up` 验证链路）。
+
+6. 更新 `scripts/reset_db.sh` 中的注释，确认脚本可用。
+
+## 迁移链路（目标状态）
+
+```
+全新数据库
+  └─ migrate up
+       ├─ 000114: 建表（squash 基线）
+       ├─ 000115: 写初始化数据
+       └─ 000116: 删除废弃字段
+```
+
+## 现有测试环境说明
+
+测试环境的表通过历史方式创建，`schema_migrations` 中仅记录版本 116。
+对正在运行的服务**没有影响**。
+若需在测试库补齐迁移记录，可手动运行 `migrate up`（000115 全部幂等，安全）。
diff --git a/scripts/reset_db.sh b/scripts/reset_db.sh
index baf8d01..3aaedf3 100755
--- a/scripts/reset_db.sh
+++ b/scripts/reset_db.sh
@@ -22,6 +22,15 @@ fi
 DB_DSN="postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}?sslmode=disable"
 ADMIN_DSN="postgres://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/postgres?sslmode=disable"
 
+# 检查 squash 基线文件是否存在（发布前必须生成，参见 migrations/README.md）
+if [ ! -f "migrations/000114_squash_baseline.up.sql" ]; then
+    echo "❌ 错误：migrations/000114_squash_baseline.up.sql 不存在！"
+    echo ""
+    echo "全新数据库需要 squash 基线文件才能通过 migrate up 建表。"
+    echo "请参考 migrations/README.md 的「发布前必做」章节生成该文件。"
+    exit 1
+fi
+
 echo "警告：即将清空数据库 ${DB_NAME}（${DB_HOST}:${DB_PORT}），5 秒后继续..."
 echo "按 Ctrl+C 取消"
 sleep 5