feat(project): init

scripts/db/README.md

@@ -0,0 +1,69 @@
+# cms-service 数据库脚本（migrate / verify / rollback）
+
+本目录提供一套与 `iam-service/scripts/db` 类似的数据库操作脚本，适用于：
+
+- 生产/预发：在启动 cms-service 前，显式执行迁移与校验
+- 开发/测试：快速初始化/回滚 schema
+
+说明：
+
+- cms-service 运行时也会自动执行 SQLx migrations（见 `src/infrastructure/db/mod.rs`）。如果你选择使用本目录脚本管理迁移，建议在部署流程中做到“先 migrate，再启动服务”，并在同一数据库上保持一致的迁移源（`cms-service/migrations/*.sql`）。
+- 本脚本会写入 SQLx 使用的 `_sqlx_migrations` 表，使得服务启动时不会重复执行已应用的迁移。
+
+## 前置条件
+
+- 已安装 `psql`
+- `DATABASE_URL` 可用（可通过导出环境变量或在项目根目录 `.env` 中配置）
+- 校验/迁移 checksum 需要 `sha384sum` 或 `openssl` + `xxd`
+
+## 常用命令
+
+```bash
+export DATABASE_URL='postgres://...'
+
+# 1) 应用迁移（写入 _sqlx_migrations）
+./scripts/db/migrate.sh
+
+# 2) 校验 schema（包含：迁移校验 + 结构校验）
+./scripts/db/verify.sh
+
+# 3) 回滚到指定版本（例如回滚到 0001）
+ROLLBACK_TO_VERSION=1 ./scripts/db/rollback.sh
+
+# 4) 回滚所有迁移（仅回滚 cms-service 自己的对象；不会卸载 pgcrypto extension）
+ROLLBACK_TO_VERSION=0 ./scripts/db/rollback.sh
+```
+
+## 版本号规则
+
+- 迁移文件目录：`cms-service/migrations/*.sql`
+- 迁移版本号：取文件名前缀数字（例如 `0002_cms.sql` -> version=2）
+- 回滚脚本：`scripts/db/rollback/<version>.down.sql`（例如 `0002.down.sql`）
+- 校验脚本：`scripts/db/verify/<version>_*.sql`
+
+## 故障排查
+
+### 启动时报 `failed to run migrations: VersionMismatch(<n>)`
+
+含义：
+
+- 数据库 `_sqlx_migrations` 表里记录的 `<n>` 号迁移 checksum，和当前仓库里对应 `migrations/<n>_*.sql` 的 checksum 不一致。
+- 常见原因是：迁移文件被改动过、或曾使用非 SQLx 算法写入了 `_sqlx_migrations.checksum`。
+
+解决（开发环境推荐做法）：
+
+1) 停止 cms-service
+2) 回滚到 0（会删除 cms 表/类型，并清理 `_sqlx_migrations` 中的记录）：
+
+```bash
+ROLLBACK_TO_VERSION=0 ./scripts/db/rollback.sh
+```
+
+3) 重新执行迁移与校验：
+
+```bash
+./scripts/db/migrate.sh
+./scripts/db/verify.sh
+```
+
+然后再启动 cms-service。