# 数据库模式

FluxiQ PIX 中所有 PostgreSQL 模式、表和关键关系的完整参考。

## 前提条件

- PostgreSQL 16 管理知识
- 了解 UUID 主键
- 熟悉[数据库配置](../configuration/database.md)

## 模式概览

| 模式 | 用途 | 关键表 |
|------|------|--------|
| `monetarie_auth` | 认证和授权 | users, sessions, institutions, groups, group_features, user_groups, mfa_configurations |
| `monetarie_dict` | DICT 目录 | dict_keys, claims, infraction_reports, cid_sync_events |
| `monetarie_spi` | SPI 交易 | messages, payments, accounts, balances, message_history, balance_history |
| `monetarie_spi_ref` | 参考数据 | banks, status_codes, reason_codes, message_types, error_codes |
| `monetarie_spi_msg` | 加密/XML | crypto_keys, private_keys, xml_messages |
| `monetarie_audit` | 审计追踪 | activity_log（已分区）, bacen_api_validations, xml_archive |
| `monetarie_settlement` | 清算/总账 | netting, reconciliation, qr_codes, chart_of_accounts, journal_entries, accounting_events, cost_centers |
| `bacen_simulator` | 模拟器 | simulator_config, scenarios, test_runs, exchanges |

## 关键表

### monetarie_auth.users

| 列 | 类型 | 描述 |
|----|------|------|
| `id` | UUID | 主键 |
| `username` | VARCHAR | 登录用户名 |
| `password_hash` | VARCHAR | Bcrypt 哈希 |
| `email` | VARCHAR | 电子邮件地址 |
| `role` | VARCHAR | 用户角色 |
| `is_active` | BOOLEAN | 账户是否活跃 |
| `is_blocked` | BOOLEAN | 账户已锁定（10 次登录失败） |
| `mfa_enabled` | BOOLEAN | MFA 是否启用 |
| `mfa_secret` | VARCHAR | TOTP 密钥（加密存储） |
| `password_expires` | TIMESTAMP | 密码过期日期 |
| `inserted_at` | TIMESTAMP | 创建时间 |
| `updated_at` | TIMESTAMP | 更新时间 |

### monetarie_spi.messages（主交易表）

| 列 | 类型 | 描述 |
|----|------|------|
| `id` | UUID | 主键 |
| `end_to_end_id` | CHAR(32) | BCB 端到端标识符 |
| `message_type` | VARCHAR | ISO 20022 类型（pacs.008 等） |
| `message_direction` | ENUM | OUTBOUND 或 INBOUND |
| `status_id` | INTEGER | 关联 status_codes（1=PDNG...10=RTRN） |
| `amount` | BIGINT | 金额（分） |
| `debtor_ispb` | CHAR(8) | 付款方机构 ISPB |
| `creditor_ispb` | CHAR(8) | 收款方机构 ISPB |
| `operation_time` | TIMESTAMP | 操作开始时间 |
| `acceptance_time` | TIMESTAMP | ACCC 时间戳 |
| `settlement_time` | TIMESTAMP | STLD 时间戳 |
| `json_input` | JSONB | 原始请求负载 |
| `inserted_at` | TIMESTAMP | 创建时间 |

::: warning 两个交易模式
`Shared.Schemas.Spi.Transaction` 映射到 `monetarie_spi.messages`（生产数据）。`SpiService.Transactions.Transaction` 映射到 `monetarie_spi.transactions`（不同的表，基本为空）。生产查询始终使用 Shared 模式。
:::

### monetarie_dict.dict_keys

| 列 | 类型 | 描述 |
|----|------|------|
| `id` | UUID | 主键 |
| `key_type` | ENUM | CPF, CNPJ, PHONE, EMAIL, EVP |
| `key_value` | VARCHAR | PIX 密钥值 |
| `participant_ispb` | CHAR(8) | 所属机构 ISPB |
| `account_number` | VARCHAR | 银行账号 |
| `branch_number` | VARCHAR | 分行代码 |
| `holder_name` | VARCHAR | 账户持有人姓名 |
| `holder_cpf_cnpj` | VARCHAR | 持有人 CPF 或 CNPJ |
| `created_at` | TIMESTAMP | 注册日期 |

### monetarie_settlement.chart_of_accounts

| 列 | 类型 | 描述 |
|----|------|------|
| `id` | UUID | 主键 |
| `code` | VARCHAR | COSIF 账户代码 |
| `name` | VARCHAR | 账户名称 |
| `type` | VARCHAR | ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE |
| `parent_id` | UUID | 父账户外键 |
| `is_active` | BOOLEAN | 激活状态 |

## 枚举类型

```sql
CREATE TYPE monetarie_dict.key_type AS ENUM ('CPF', 'CNPJ', 'PHONE', 'EMAIL', 'EVP');
CREATE TYPE monetarie_spi.debit_credit AS ENUM ('DEBIT', 'CREDIT');
CREATE TYPE monetarie_spi.message_direction AS ENUM ('OUTBOUND', 'INBOUND');
```

## 关键索引

| 表 | 列 | 类型 | 用途 |
|----|-----|------|------|
| messages | `(end_to_end_id::text)` | GIN 三元组 | E2E 模糊搜索 |
| messages | `status_id` | B-tree | 状态过滤 |
| messages | `branch_id, status_id` | 复合 | 分行仪表板 |
| messages | `inserted_at` | B-tree | 日期范围查询 |
| payments | `debtor_cpf_cnpj` | B-tree | CPF/CNPJ 查询 |
| dict_keys | `key_type, key_value` | 复合 | 密钥查询 |
| message_history | `message_id, inserted_at` | 复合 | 历史查询 |
| balance_history | `account_id, recorded_at` | 复合 | 余额历史 |

## 分区表

| 表 | 分区键 | 策略 | 保留 |
|----|--------|------|------|
| `monetarie_audit.activity_log` | `created_at` | 按月 RANGE | PartitionManager |
| `monetarie_auth.login_history` | `login_at` | 按月 RANGE | PartitionManager |

分区：2026-01 到 2026-04 + DEFAULT 分区。

## 状态 ID 映射

| ID | 代码 | 描述 |
|----|------|------|
| 1 | PDNG | 待处理 |
| 2 | ACSP | 已接受处理 |
| 3 | ACCC | 已接受 |
| 4 | ACSC | 已接受清算完成 |
| 5 | ACTC | 技术性接受 |
| 6 | ACWC | 有变更接受 |
| 7 | STLD | 已清算 |
| 8 | RJCT | 已拒绝 |
| 9 | CANC | 已取消 |
| 10 | RTRN | 已退回 |

## 预期结果

查阅本模式参考后：

- 完全了解 8 个数据库模式
- 了解关键表、列和关系
- 了解查询优化的索引
- 了解两个 Transaction 模式的映射