Initial LisgloSIPS V2 implementation

docs/DATABASE_SCHEMA_RUNBOOK.md

@@ -0,0 +1,66 @@
+# 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 不写入明文密码。