# BACEN 连接

配置 FluxiQ PIX 通过 RSFN（国家金融系统网络）连接到巴西中央银行的 DICT 和 SPI 服务。

## 前提条件

- 机构已注册为 BCB 的 SPI 参与者
- ICP-Brasil 证书（CPIC + CPIA）已签发且有效
- 到 RSFN 端点的网络访问（防火墙规则已配置）
- 熟悉[证书](./certificates.md)配置

## BACEN 环境

| 环境 | DICT URL | ICOM/SPI 主通道 | ICOM/SPI 辅通道 |
|------|----------|------------------|------------------|
| 同源 | `https://dict-h.pi.rsfn.net.br:16522/api/v2` | `https://icom-h.pi.rsfn.net.br:16522` | `https://icom-sec-h.pi.rsfn.net.br:17522` |
| 生产 | `https://dict.pi.rsfn.net.br:16522/api/v2` | `https://icom.pi.rsfn.net.br:16522` | `https://icom-sec.pi.rsfn.net.br:17522` |

## 通道路由 (CPM/CSM)

`Shared.Bacen.ChannelRouter` GenServer 将消息路由到适当的 BACEN 通道：

```mermaid
graph LR
    MSG[消息] --> CR{通道路由器}
    CR -->|金融| CPM[主通道<br/>:16522]
    CR -->|非金融| CSM[辅通道<br/>:17522]
    CPM -.->|故障转移| CSM
    CSM -.->|故障转移| CPM
```

- **金融消息** (pacs.008, pacs.004) -> 主通道 (CPM, 端口 16522)
- **非金融消息** (pacs.002, pacs.028) -> 辅通道 (CSM, 端口 17522)
- **自动故障转移**：健康 -> 降级（2 次失败）-> 停机（3 次失败）
- **恢复检查**：每 2 分钟对停机通道进行检查

### 配置

| 变量 | 默认值 | 描述 |
|------|--------|------|
| `BACEN_FAILOVER_ENABLED` | `true` | 启用 CPM/CSM 自动故障转移 |
| `BACEN_FAILURE_THRESHOLD` | `3` | 标记通道不活跃前的失败次数 |
| `BACEN_HEALTH_CHECK_INTERVAL` | `30` | 健康检查间隔（秒） |

## 错误处理 (RFC 7807)

BACEN 以 RFC 7807 `application/problem+json` 格式返回错误。FluxiQ PIX 通过以下方式处理：

- **`Shared.Bacen.ProblemDetails`**：为所有错误类型构建 RFC 7807 响应
- **`Shared.Bacen.ErrorLookup`**：ETS 缓存的 GenServer，10 分钟刷新 BACEN 错误代码
- 40+ 错误原因 -> HTTP 状态码映射
- Content-Type：`application/problem+json`

## 模拟器模式

无需 BACEN 连接进行测试：

```bash
SIMULATOR_ENABLED=true
BACEN_ENABLED=false
```

模拟器提供：
- 8 个预配置场景（happy_path、rejected_payment、return_flow 等）
- 11 个模拟器 API 端点，位于 `/api/v1/simulator` 下
- 模拟 DICT 查询和 SPI 消息处理
- 集成测试支持（200 笔交易：100 笔发送 + 100 笔接收）

::: danger 切勿在生产环境使用
模拟器会覆盖真实的 BACEN 通信。切勿在生产环境中启用 `SIMULATOR_ENABLED=true`。
:::

## 审计要求

BCB 要求全面的审计跟踪：

| 要求 | 实现 |
|------|------|
| ICOM 消息保留 | 10 年 |
| DICT 读取保留 | 2 年 |
| XML 归档 | 每个归档 XML 的 SHA-256 哈希 |
| 验证日志 | 存储在 `monetarie_audit.bacen_api_validations` |
| 导出格式 | 压缩 JSONL 用于冷存储 |

## XSD 验证

FluxiQ PIX 使用双重策略验证所有 BACEN 消息：

1. **结构验证**：`:xmerl` + Elixir 规则用于快速检查
2. **XSD 文件验证**：`xmllint` 用于完整的模式合规性

支持 27 种消息类型模式，具有必需字段和格式规则。验证通过 `Task.start` 在入站和出站消息上异步运行。

## 预期结果

配置 BACEN 连接后：

- 到 DICT 和 SPI 同源端点的 mTLS 连接已建立
- 通道路由已激活（CPM 用于金融，CSM 用于非金融）
- 通道间自动故障转移正常运行
- 错误响应采用 RFC 7807 格式
- 审计跟踪记录所有 BACEN 交互