# 清算

PIX 参与者之间的清算周期管理、净额计算、对账和余额管理。

## 前提条件

- 了解 PIX 清算机制
- 拥有清算权限的管理员访问
- 后端运行中，NATS workers 已激活

## 清算概览

PIX 清算有两种模式：

1. **实时清算**：单笔交易清算（pacs.008 -> pacs.002 -> STLD）
2. **定期净额计算**：BCB 汇总双边头寸以最小化流动性需求

```mermaid
graph LR
    TX[交易] --> NET[净额计算周期]
    NET --> CALC[计算头寸]
    CALC --> SETTLE[清算净额]
    SETTLE --> RECON[对账]
```

## 清算 Workers

| Worker | 用途 | 调度 |
|--------|------|------|
| Scheduler | 发起清算周期 | 可配置间隔 |
| FileImporter | 导入 BCB 清算文件 | 文件到达时 |
| CoreEventProcessor | 处理 Core Banking 事件 | 持续 |

### Scheduler

Scheduler worker：
- 获取当前清算窗口的交易（LIMIT 500K，30秒超时）
- 按参与者对分组
- 计算净头寸
- 创建清算记录

## 对账

对账模块识别以下之间的差异：
- 内部交易记录
- BCB 清算确认
- 参与者余额报告

```bash
# API 端点
GET /api/v1/settlement/reconciliation
```

所有对账查询具有 `LIMIT 10,000` 安全限制，防止大数据集上的 OOM。

## 余额管理

| 端点 | 方法 | 描述 |
|------|------|------|
| `/api/v1/settlement/balances` | GET | 每个参与者的当前余额 |
| `/api/v1/settlement/balances/:ispb` | GET | 特定参与者的余额 |

余额操作包装在 `Repo.transaction` 中，带有零金额验证以防止会计错误。

## 断路器

跨服务调用（Settlement -> Dict、Settlement -> SPI）受 `SettlementService.CircuitBreaker` 保护：

| 状态 | 行为 |
|------|------|
| Closed | 正常运行 |
| Open | 快速失败（5 次故障后） |
| Half-Open | 30 秒冷却后单次探测请求 |

只有 5xx 和传输错误触发断路器。4xx 响应是客户端错误，不影响断路器状态。

## 清算事件 (NATS)

| 主题 | 描述 |
|------|------|
| `monetarie.settlement.cycle.started` | 新的清算周期已启动 |
| `monetarie.settlement.cycle.completed` | 周期成功完成 |
| `monetarie.settlement.reconciliation.discrepancy` | 发现差异 |
| `monetarie.settlement.balance.updated` | 参与者余额已变更 |

## 预期结果

配置清算后：

- 清算周期按计划运行
- 净额计算产生正确的双边头寸
- 对账识别差异
- 余额操作原子化并已验证
- 断路器防止级联故障