lisglosips/docs/DATABASE_SCHEMA_RUNBOOK.md

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 合同测试。

标准初始化

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

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 文件或部署环境变量，禁止写入仓库。

验证命令

pnpm prisma:validate
pnpm typecheck
pnpm test
pnpm build

数据库侧验收：

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

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

回滚与恢复

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

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 不写入明文密码。