67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# 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 不写入明文密码。
|