# 模拟器

BACEN PIX 模拟器可以在没有真实中央银行连接的情况下测试 PIX 流程。

## 前提条件

- 环境变量中 `SIMULATOR_ENABLED=true`
- `BACEN_ENABLED=false`（模拟器替代真实 BACEN 通信）
- 后端运行中且健康

::: danger 生产环境警告
切勿在生产环境中启用模拟器。它会覆盖真实的 BACEN 通信行为。
:::

## 架构

`Shared.Bacen.Simulator` GenServer 在 `SIMULATOR_ENABLED=true` 时有条件地在 `Shared.Application` 监督树中启动。

```mermaid
graph TB
    API[模拟器 API<br/>/api/v1/simulator] --> GS[Simulator GenServer]
    GS --> DICT[模拟 DICT]
    GS --> SPI[模拟 SPI]
    GS --> SCEN[场景引擎]
```

## API 端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/simulator/status` | 模拟器状态和配置 |
| PUT | `/api/v1/simulator/config` | 更新模拟器设置 |
| POST | `/api/v1/simulator/process` | 处理模拟消息 |
| POST | `/api/v1/simulator/inbound` | 模拟来自 BACEN 的入站消息 |
| GET | `/api/v1/simulator/scenarios` | 列出可用场景 |
| POST | `/api/v1/simulator/scenarios/:id/run` | 执行场景 |
| GET | `/api/v1/simulator/test-runs` | 列出测试运行结果 |
| GET | `/api/v1/simulator/test-runs/:id` | 获取测试运行详情 |
| GET | `/api/v1/simulator/exchanges` | 列出消息交换 |

## 预配置场景

| 场景 | 描述 |
|------|------|
| `happy_path` | 成功的 PIX 支付端到端 |
| `rejected_payment` | 被贷方机构拒绝的支付 |
| `return_flow` | 完整的退回（pacs.004）流程 |
| `incoming_payment` | 接收入站 PIX 支付 |
| `echo_test` | BACEN 连接测试（pibr.001/002） |
| `balance_check` | 清算余额查询（camt.060） |
| `full_cycle` | 完整周期：发送 + 接收 + 清算 |
| `stress_test` | 高容量交易突发 |

## 运行场景

```bash
# 列出场景
curl http://localhost:4003/api/v1/simulator/scenarios

# 运行 happy_path
curl -X POST http://localhost:4003/api/v1/simulator/scenarios/happy_path/run \
  -H "Content-Type: application/json" \
  -H "Cookie: pix_session=YOUR_JWT"

# 检查结果
curl http://localhost:4003/api/v1/simulator/test-runs
```

## 集成测试

模拟器支持完整的集成测试：

- 测试 200 笔交易：100 笔发送（MONETARIE -> MW）+ 100 笔接收（MW -> MONETARIE）
- 清算延迟：300-1500ms（符合 ANS）
- 状态分布：85-90% STLD、5-10% ACSP、5% PDNG

### 模拟数据

| 数据 | 数量 |
|------|------|
| DICT 条目 | 20 |
| SPI 余额 | 12 |
| 场景 | 10 |
| 模拟器配置 | 10 |

## 安全说明

- `SimulatorController` 使用 `String.to_existing_atom` 和白名单防止原子表 DoS
- `sanitize_for_json` 安全处理 Decimal、DateTime、NaiveDateTime 和结构体类型

## 预期结果

启用模拟器后：

- 8 个场景可用于测试
- DICT 查询返回模拟数据
- SPI 消息在无 BACEN 连接的情况下处理
- 集成测试通过（200/200 SUCCESS）
- 测试运行结果存储在 `bacen_simulator` 模式中