# 数据库跨域模型与治理基线（v1.0）

- 版本：v1.0
- 日期：2026-03-27
- 状态：生效（数据库设计 SSOT 补丁）
- 适用范围：S0-S2 执行与验收
- 关联文档：
  - `docs/llm_gateway_prd_v1_2026-03-25.md`
  - `docs/supply_technical_design_enhanced_v1_2026-03-25.md`
  - `docs/technical_architecture_optimized_v2_2026-03-18.md`
  - `sql/postgresql/supply_schema_v1.sql`
  - `sql/postgresql/supply_schema_v1_patch_2026-03-27.sql`
  - `sql/postgresql/platform_core_schema_v1.sql`

---

## 1. 本次补齐的缺口

1. 仅有 `supply_*` 表，缺少 PRD P0/P1 的核心域（租户/项目/鉴权 key/账务总账/审计事件）。
2. 供应域缺少统一加密元数据字段，无法审计算法、KMS Key 版本与轮换状态。
3. 缺少统一单位字段（quota/cost/amount unit），跨域统计口径不稳定。
4. 审计字段不完整（request_id、trace_id、IP、operator、version）。
5. 索引以单列为主，未覆盖高频组合查询（租户+状态+时间）。

---

## 2. 最小跨域表模型（按 PRD P0/P1）

| 域 | 表 | 说明 |
|---|---|---|
| Core | `core_tenants` | 组织/租户主实体 |
| Core | `core_projects` | 项目/成本归因单元 |
| IAM | `iam_users` | 用户身份与角色 |
| Auth | `auth_platform_api_keys` | 平台签发凭证（仅 hash，不存明文） |
| Billing | `billing_accounts` | 预算账户与余额 |
| Billing | `billing_ledger_entries` | 借贷分录与请求级对账 |
| Routing | `routing_policies` | 策略版本、优先级、生效窗口 |
| Security | `security_kms_key_registry` | KMS Key 与加密算法版本登记 |
| Audit | `audit_events` | 全域审计事件（配置/账务/安全） |

DDL：`sql/postgresql/platform_core_schema_v1.sql`

---

## 3. 供应域字段补齐（在 v1 基础上增量）

### 3.1 加密字段（必须）

1. `*_cipher_algo`：默认 `AES-256-GCM`
2. `*_kms_key_alias`：KMS key alias（非 key 明文）
3. `*_key_version`：key 版本号
4. `*_fingerprint`：凭证摘要（不可逆）
5. `last_rotation_at`：上次轮换时间

### 3.2 单位与币种字段（必须）

1. `quota_unit`：`token/request/credit`
2. `price_unit`：`per_1m_tokens` 等
3. `amount_unit`：`minor`（分/厘）
4. `currency_code`：ISO 4217 三位码

### 3.3 审计与并发字段（必须）

1. `request_id`
2. `idempotency_key`
3. `audit_trace_id`
4. `created_ip` / `updated_ip`
5. `version`（乐观锁）

DDL：`sql/postgresql/supply_schema_v1_patch_2026-03-27.sql`

---

## 4. 索引策略（高频查询优先）

### 4.1 组合索引

1. `supply_accounts(user_id, status, updated_at desc)`
2. `supply_packages(user_id, status, updated_at desc)`
3. `supply_orders(buyer_user_id, status, created_at desc)`
4. `supply_settlements(user_id, status, updated_at desc)`
5. `billing_ledger_entries(billing_account_id, occurred_at desc)`

### 4.2 部分索引

1. `supply_packages` 的 active 查询（仅 `status=active`）
2. `supply_settlements` 的处理中唯一约束（仅 `status=processing`）

### 4.3 可观测索引

1. `request_id`
2. `trace_id`
3. `audit_trace_id`

说明：所有关键事件必须具备 request 级反查路径，满足“从告警到原始账务分录”单跳可达。

---

## 5. 迁移顺序与回滚策略

1. Phase-A：执行 `platform_core_schema_v1.sql`（新增表，无破坏性）。
2. Phase-B：执行 `supply_schema_v1_patch_2026-03-27.sql`（增列+增索引）。
3. Phase-C：灰度写入新字段（双写，不读取）。
4. Phase-D：回填历史数据（按日批，带校验）。
5. Phase-E：切换读路径到新字段并开启质量门禁。

回滚原则：
1. 新字段只增不删，读路径可切回旧字段。
2. 新索引可独立回退，不影响主流程事务。
3. 任一阶段失败立即冻结下一阶段，不跨阶段带病推进。

---

## 6. 质量验收清单（DB）

1. 结构验收：新增表/列/索引全部存在，且命名符合规范。
2. 安全验收：无明文凭证列，hash/指纹字段可用。
3. 一致性验收：账务分录借贷平衡，提现处理中单一约束生效。
4. 审计验收：关键写接口 100% 带 `request_id + trace_id`。
5. 性能验收：高频查询 P95 无劣化（对比 patch 前后）。

---

## 7. 约束声明

1. 本文与两个 SQL 文件共同构成数据库实施 SSOT。
2. 任何新增业务功能必须先选择所属域，再定义表/字段/索引，不允许“先代码后补库”。
3. 未通过本清单第 6 章，禁止进入发布门禁 `SUP-008` 与全局 `GO` 评审。