# 数据库脚本（版本化迁移）

## 目录结构

- `migrations/`：按版本顺序的升级脚本（只增不改）
- `rollback/`：与 migration 一一对应的回滚脚本（按版本号匹配）
- `migrate.sh`：按顺序执行未应用的 migrations
- `rollback.sh`：按版本回滚（需要显式确认）
- `verify.sh`：执行校验脚本，确认表结构与种子数据满足要求
- `reset.sh`：开发/测试用清库重置（会删除所有 IAM 表与迁移记录，需显式确认）
- `rebuild_iam_db.sh`：开发环境一键重建（会清库重建，不适合生产）

## 版本与执行顺序

| 版本 | 脚本 | 说明 |
|---|---|---|
| 0001 | `migrations/0001_core.sql` | IAM 核心表（tenant/user/role/permission 等）与基础种子数据 |
| 0002 | `migrations/0002_enabled_apps.sql` | enabled_apps（租户应用开通）、平台租户与平台权限（SuperAdmin） |

校验脚本映射（与 migrations 一一对应）：

| 版本 | 校验脚本 | 说明 |
|---|---|---|
| 0001 | `scripts/db/verify/0001_core.sql` | 校验核心表、索引与基础种子 |
| 0002 | `scripts/db/verify/0002_enabled_apps.sql` | 校验 enabled_apps 相关表与平台种子 |

## 执行方式

环境变量：
- `DATABASE_URL`：必填（也可放在项目根目录 `.env` 中）
依赖：
- 需要安装 PostgreSQL 客户端工具（`psql`）；可选 `pg_dump`（仅当你要做备份）。

执行迁移：

```bash
./scripts/db/migrate.sh
./scripts/db/verify.sh
```

开发/测试环境清库重置（危险）：

```bash
CONFIRM=1 ./scripts/db/reset.sh
```

回滚到指定版本（示例：回滚到 0001）：

```bash
CONFIRM=1 TARGET_VERSION=0001 ./scripts/db/rollback.sh
./scripts/db/verify.sh
```

验证步骤

- 执行 `./scripts/db/verify.sh`，应无错误退出
- 启动服务后通过 Scalar 访问 `/scalar`，检查 OpenAPI 中包含：
  - `/platform/tenants/{tenant_id}/enabled-apps`
  - `/users/{id}/roles`

## 首次环境准备（DB/User）

在具有足够权限的数据库账号下执行（示例）：

```sql
CREATE USER iam_service_user WITH PASSWORD 'iam_service_password';
CREATE DATABASE iam_service_db OWNER iam_service_user;
GRANT ALL PRIVILEGES ON DATABASE iam_service_db TO iam_service_user;
```

说明：
- 生产环境不要在仓库内硬编码密码；应由密钥管理系统注入并轮换。
- 如需启用扩展（如 `uuid-ossp`），请确认应用账号是否有权限，或由 DBA 预先安装。

## 常见问题

### `.env` 配了 DATABASE_URL 但脚本报 “DATABASE_URL is required”

`.env` 只是文件，不会自动变成进程环境变量。Rust 程序会通过 `dotenvy` 读取 `.env`，但 bash 脚本默认不会。

解决方式：
- 直接 `export DATABASE_URL=...` 后再执行脚本；或
- 保持项目根目录存在 `.env`，脚本会尝试读取其中的 `DATABASE_URL`。

### 执行脚本报 “psql not found”

原因：系统未安装 PostgreSQL 客户端工具（`psql`/`pg_dump`），或不在 `PATH` 中。

安装方式：
- Ubuntu/Debian：`sudo apt-get update && sudo apt-get install -y postgresql-client`
- RHEL/CentOS/Fedora：`sudo dnf install -y postgresql`
- Alpine：`sudo apk add postgresql-client`
- macOS（Homebrew）：`brew install libpq && brew link --force libpq`

验证方式：

```bash
psql --version
```