# LisgloSIPS V2 数据库 Schema 与迁移 Runbook

## 范围

本文对应 `S08 - 数据库 Schema 与迁移`。业务数据库使用 MySQL，Schema 由 `prisma/schema.prisma` 管理，初始化迁移位于 `prisma/migrations/20260621090000_init_v2_schema/`。

## 本次产物

- `prisma/schema.prisma`：V2 核心业务表、索引、关系、枚举和审计列。
- `prisma/migrations/20260621090000_init_v2_schema/migration.sql`：从空库初始化的 SQL 迁移。
- `prisma/seed.ts`：内置权限和角色种子；不创建默认密码用户。
- `packages/database/src/schema-contract.spec.ts`：Schema 合同测试。

## 标准初始化

只在空库或明确的新环境执行：

```bash
export DATABASE_URL='mysql://<APP_USER>@127.0.0.1:3306/<DATABASE_NAME>'
pnpm prisma:generate
pnpm exec prisma migrate deploy
pnpm db:seed
```

`DATABASE_URL` 示例不包含密码。实际凭据必须来自受控 Secret 文件或部署环境变量，禁止写入仓库。

## 验证命令

```bash
pnpm prisma:validate
pnpm typecheck
pnpm test
pnpm build
```

数据库侧验收：

```bash
pnpm exec prisma migrate deploy
pnpm exec prisma migrate status
pnpm db:seed
pnpm db:seed
```

重复执行 `migrate deploy` 和 `db:seed` 应安全：迁移不会重复应用，seed 使用 upsert。

## 回滚与恢复

初始化迁移只允许用于空库。若在临时库验证失败：

```sql
DROP DATABASE <TEMP_DATABASE_NAME>;
DROP USER '<TEMP_USER>'@'127.0.0.1';
DROP USER '<TEMP_USER>'@'localhost';
```

生产或准生产环境禁止依赖破坏性 down migration 回滚。若迁移已进入共享环境，应优先发布向前兼容修复迁移；上线窗口不执行不可逆删列。

## 重要约束

- 金额字段统一 `DECIMAL(20,6)`。
- 充值、CDR、审计日志不做物理删除。
- `raw_cdrs.event_id` 和 `raw_cdrs.call_id + ended_at` 保证 CDR 幂等。
- 充值表和 `idempotency_keys` 均有幂等唯一键。
- 所有管理类表包含 `created_at`、`updated_at`、`created_by`、`updated_by`、`version`。
- 密码字段只保存 hash 或 SIP Digest HA1，seed 不写入明文密码。