# 数据库迁移指南（Alembic）

> 本项目用 **Alembic** 管理数据库表结构。所有"建表/改表"都写成 `alembic/versions/` 下的迁移脚本，
> 数据库的真实结构 = 把这些迁移按顺序跑一遍的结果。**不要手动改库结构**，一律走迁移。
>
> **相关文档**:
> - 这份文档讲 **alembic 操作**(如何建表/升级/新增迁移/多 head 排查)
> - [postgres-migration.md](./postgres-migration.md) 讲 **从 SQLite 切到 PostgreSQL** 的完整步骤(本机安装/建库/`scripts/init_postgres.py` 用法)
> - 配合 [后端技术实现.md §10](./后端技术实现.md) 看待办与已知问题

---

## 一句话
**clone 项目 / 拉到新迁移后，跑一条命令即可：**
```bash
alembic upgrade head
```
它会把数据库结构升到最新（幂等，已是最新则什么都不做）。

**新 PG 环境从零开始**:跑 `python scripts/init_postgres.py`,它会建用户 + 建库 + 写 .env + 跑迁移。详见 [postgres-migration.md](./postgres-migration.md)。

---

## 1. 首次初始化（clone 后）

### 1.1 用 PostgreSQL（推荐，与生产一致）
前置:本机已装 PostgreSQL 16 + 知道 postgres 超级用户密码。

```bash
# (1) 装依赖(在你的虚拟环境里, 含 psycopg)
pip install -e .

# (2) 一键建用户 + 建库 + 写 .env + 跑迁移
python scripts/init_postgres.py
# 按提示输入 PG 超级用户密码即可。脚本会:
#   - 自动建业务用户 shaguabijia_app + 业务库 shaguabijia
#   - 自动生成业务用户强密码,写入 .env 的 DATABASE_URL
#   - 跑完 alembic upgrade head

# (3) 启动
./run.sh
```

可用环境变量提前指定(免交互):
```bash
PG_SUPER_PASS=xxx APP_DB_PASS=yyy python scripts/init_postgres.py
```
脚本幂等,重复跑会重置业务用户密码、跳过已存在的库。

### 1.2 用 SQLite(本地开发临时用,不接生产链路时)
```bash
pip install -e .
cp .env.example .env       # 不动 DATABASE_URL, 默认 sqlite:///./data/app.db
mkdir -p data
alembic upgrade head
./run.sh
```
> 也可以直接 `bash scripts/migrate.sh` 只做迁移、不启服务（部署/CI 用）。

## 2. 数据库地址从哪来
- 由 `settings.DATABASE_URL` 决定（`app/core/config.py`），可在 `.env` 用 `DATABASE_URL=` 覆盖。
- 默认 **SQLite**：`sqlite:///./data/app.db`（所以要先 `mkdir -p data`）。
- 切 **PostgreSQL**：`.env` 里设 `DATABASE_URL=postgresql+psycopg://user:pwd@host:5432/dbname`，再 `alembic upgrade head` 即可（迁移脚本用了 `render_as_batch` 兼容 SQLite，Postgres 也能跑）。
- `alembic.ini` 的 `sqlalchemy.url` 故意留空，由 `alembic/env.py` 从 `settings` 注入，**别在 alembic.ini 里填库地址**。

## 3. 常用命令
| 命令 | 作用 |
|---|---|
| `alembic upgrade head` | 升到最新（最常用） |
| `alembic current` | 看当前库在哪个 revision |
| `alembic history` | 看迁移链（谁接谁） |
| `alembic heads` | 看有几个 head（正常只 1 个；出现多个 = 分叉了要 merge） |
| `alembic downgrade -1` | 回滚一步（**生产慎用**，会丢数据） |
| `alembic downgrade <revision>` | 回滚到指定版本 |

## 4. 改了 ORM model、要新增一次结构变更
```bash
# 1) 自动对比 models 与库,生成迁移草稿
alembic revision --autogenerate -m "add xxx index"
# 2) **务必打开生成的文件 review**(autogenerate 不完美,索引/默认值/数据迁移常需手改)
# 3) 应用
alembic upgrade head
```

---

## 5. 关于迁移文件名（重要）
- 文件名是 `<描述>.py`（如 `welfare_tables_coin_account_coin_txn.py`）。**早期带的 hex 前缀已去掉，只是文件名变干净**。
- **真正的版本 id 是文件内的 `revision` 变量**（如 `revision = '357520ea3015'`），迁移链靠文件内的 `down_revision` 串起来，**与文件名无关**。数据库 `alembic_version` 表里存的也是这个内部 id。
- 因此：**可以随意重命名迁移文件**（Alembic 靠扫描文件、读 `revision` 识别），但 **绝不要改文件内的 `revision` / `down_revision`**——改了会和已迁移过的库（含生产）对不上，报"找不到 revision"。
- ⚠️ `alembic revision --autogenerate` **默认仍生成带 hex 前缀的文件名**。想保持本目录"无前缀"风格，二选一：
  - 生成后**手动把文件名前缀去掉**（内部 id 别动）；或
  - 在 `alembic.ini` 配 `file_template = %%(slug)s`（注意 ini 里 `%` 要写成 `%%`）让以后直接生成无前缀文件名（缺点：同名 slug 会冲突，描述写具体点）。

## 6. 当前迁移链(12 条,含合并迁移)
```
init_user_table                                    ← 起点(down_revision=None)
  → welfare_tables_coin_account_coin_txn           金币账户/金币流水/签到/任务表
  → cash_transaction_table                         现金流水表
  → savings_record_table                           省钱明细表
  → withdraw_order_and_user_openid                 提现单表 + user.wechat_openid
  → user_wechat_nickname_avatar                    user 微信昵称/头像字段
  → unique_wechat_openid                           user.wechat_openid 唯一约束
  → savings_shop_dishes                            省钱明细 shop_name + dishes
  → ad_reward_record                               看广告发奖记录表
  → (此处分叉,两条并行 head)
       ├→ feedback_table                          帮助与反馈表(PR #4)
       └→ ef96beb47b1e_convert_savings_record_dishes_from_json   dishes 列改 JSONB(PR #6)
  → f01db5d77dac_merge_pg_jsonb_and_feedback_heads (head,最新)  合并两条分叉
```
> 顺序以 `alembic history` 输出为准（按 `down_revision` 链，不是文件名字母序）。

## 7. 踩坑

### SQLite 找不到目录
报 `unable to open database file` → 先 `mkdir -p data`。

### 多 head 分叉(2026-05-29 撞过)

`alembic upgrade head` 报:
```
Multiple head revisions are present for given argument 'head';
please specify a specific target revision, '<branchname>@head'...
```

**原因**:跨分支并行开发,两条分支都加了新迁移且 `down_revision` 都指向同一个 commit,合并到 main 后形成两条平行链。本次实例:
- PR #4 (feedback) 加了 `d1e2f3a4b5c6`,`down_revision='c8d9e0f1a2b3'` (ad_reward)
- PR #6 (PG/JSONB) 加了 `ef96beb47b1e`,`down_revision='c8d9e0f1a2b3'`(也是 ad_reward) ← 跟 #4 同源,撞车
- 两个 PR 都合进 main 后,`alembic heads` 出现两个

**修复**:
```bash
alembic heads                                    # 列出冲突的两个 head id
alembic merge -m "merge <description>" <head1> <head2>
# 生成一个空迁移文件,把两个 head 合成新的单一 head
git add alembic/versions/<new_merge_file>.py
# commit + push, PR review 后合并到 main
```

**预防(团队规约)**:
- 写迁移的 PR 在提交前跑 `alembic heads`,确认本分支只有一个 head
- review 别人含迁移的 PR 时,看 `down_revision` 是否还是当前 main 的最新——如果上游已经被别人合了新迁移,需要 rebase 修改 `down_revision` 指过去
- main 拉新代码后再跑一次 `alembic heads` 兜底
- **生产库**：不要随意 `downgrade`；新迁移先在本地/测试库验证过再上。生产 `DATABASE_URL` 由部署侧配置，不在本仓库 `.env`。