# 架构

FluxiQ PIX 平台的详细技术架构，涵盖 Elixir umbrella 结构、服务边界、数据流和基础设施组件。

## 前提条件

- 熟悉 Elixir/OTP 监督树
- 理解微服务通信模式
- 了解 ISO 20022 消息标准基础知识

## Umbrella 架构

FluxiQ PIX 使用 Elixir umbrella 项目，包含 4 个 OTP 应用，每个都有专门的职责和端口：

```mermaid
graph LR
    subgraph Umbrella [FluxiQ PIX Umbrella]
        SHARED[shared<br/>数据库, 认证, 加密, NATS]
        DICT[dict_service<br/>:4001]
        SPI[spi_service<br/>:4002]
        SETTLE[settlement_service<br/>:4003 API 网关]
    end
    DICT --> SHARED
    SPI --> SHARED
    SETTLE --> SHARED
    SETTLE -->|HTTP 代理| DICT
    SETTLE -->|HTTP 代理| SPI
```

| 应用 | 端口 | 端点数 | 职责 |
|------|------|--------|------|
| `shared` | -- | -- | PostgreSQL schemas、Ecto Repo、JWT/MFA 认证、ICP-Brasil 加密、NATS 连接、Redis 客户端、BACEN HTTP 客户端 |
| `dict_service` | 4001 | ~92 | DICT v2.10.0 API -- PIX 密钥生命周期 (创建、查询、删除、认领、携转)、CID 同步 |
| `spi_service` | 4002 | ~95 | SPI -- ISO 20022 消息处理 (pacs.008、pacs.002、pacs.004、pacs.028)、入站/出站流 |
| `settlement_service` | 4003 | ~200 | API 网关、清算周期、净额计算、对账、会计、监控、管理 API |

## 服务通信

### 内部 (同步)

Settlement Service 作为 API 网关，通过 HTTP 将请求代理到 Dict 和 SPI 服务：

```
Client --> Settlement(:4003) --HTTP--> Dict(:4001)
Client --> Settlement(:4003) --HTTP--> SPI(:4002)
```

`SettlementService.InternalClient` 模块处理服务间调用，具备：
- 断路器 (5 次失败 -> 打开，30 秒冷却)
- 分布式追踪传播 (`x-trace-id` 头)
- Finch 连接池 (DICT: 10x2=20 连接，默认: 25x2=50 连接)

### 外部 (异步)

NATS JetStream 提供持久的 at-least-once 交付，用于事件驱动通信：

```mermaid
graph LR
    SPI -->|monetarie.spi.*| NATS[NATS JetStream]
    DICT -->|monetarie.dict.*| NATS
    SETTLE -->|monetarie.settlement.*| NATS
    NATS -->|monetarie.core.*| CORE[核心银行]
    CORE -->|monetarie.core.pix.*| NATS
```

### 7 个 JetStream 流

| 流 | 主题 | 保留期 | 用途 |
|----|------|--------|------|
| `MONETARIE_SPI` | `monetarie.spi.>` | 7 天 | SPI 交易事件 |
| `MONETARIE_DICT` | `monetarie.dict.>` | 7 天 | DICT 密钥管理事件 |
| `MONETARIE_SETTLEMENT` | `monetarie.settlement.>` | 7 天 | 清算/对账事件 |
| `MONETARIE_AUDIT` | `monetarie.audit.>` | 90 天 | 审计追踪 |
| `MONETARIE_DLQ` | `monetarie.dlq.>` | 90 天 | 死信队列 |
| `MONETARIE_CORE` | `monetarie.core.>` | 7 天 | 核心银行集成事件 |

## 数据架构

### PostgreSQL Schemas (8 个)

| Schema | 表 | 用途 |
|--------|-----|------|
| `monetarie_auth` | 用户、会话、MFA、机构、组 | 认证和授权 |
| `monetarie_dict` | PIX 密钥、认领、MED 2.0、CID 同步 | DICT 目录数据 |
| `monetarie_spi` | 消息、支付、账户、余额 | SPI 交易数据 |
| `monetarie_spi_ref` | 银行、状态码、消息类型 | 参考/查询数据 |
| `monetarie_spi_msg` | 加密密钥、XML 消息 | 加密材料 |
| `monetarie_audit` | XML 存档、BACEN 验证 | 审计和合规 |
| `monetarie_settlement` | 净额计算、对账、QR 码、总账 | 清算和会计 |
| `bacen_simulator` | 配置、场景、测试运行 | BACEN 模拟器数据 |

### Redis 用途

| 用途 | 键模式 | TTL |
|------|--------|-----|
| 速率限制 | `rate_limit:{ip}:{path}` | 15 分钟 |
| Token 黑名单 | `blacklist:{jti}` | 剩余 JWT TTL |
| 幂等性 | `idempotency:{user}:{key}` | 24 小时 |
| 会话缓存 | `session:{token}` | 可配置 |

## 监督树

每个 OTP 应用都有自己的监督树，重启策略针对弹性进行了调优：

```mermaid
graph TD
    SHARED_APP[Shared.Application<br/>one_for_one, 10/60s]
    SHARED_APP --> PG[PostgrexSupervisor]
    SHARED_APP --> REPO[Shared.Repo]
    SHARED_APP --> FINCH[Finch]
    SHARED_APP --> TEL[Telemetry]
    SHARED_APP --> RED[Redis Connection<br/>10 连接池]
    SHARED_APP --> CERT[CertificatePool<br/>5 分钟刷新]
    SHARED_APP --> CHAN[ChannelRouter<br/>健康追踪]
    SHARED_APP --> ERR[ErrorLookup<br/>10 分钟 ETS 刷新]
    SHARED_APP --> NATS_SUP[NATS Supervisor<br/>条件启动]
    SHARED_APP --> PART[PartitionManager<br/>每日检查]
```

### Worker 处理模型

NATS workers 使用 `BaseWorker` 并支持可配置并行度：

| Worker | 批量大小 | 轮询间隔 | 最大并发 |
|--------|----------|----------|----------|
| InboundProcessor | 100 | 200ms | 10 |
| OutboundSender | 100 | 200ms | 10 |
| StatusUpdater | 100 | 200ms | 10 |
| ReturnProcessor | 100 | 200ms | 5 |
| CoreEventProcessor | 50 | 500ms | 5 |

Workers 具有自适应背压：满批次 -> 50ms 轮询，空 -> 2000ms 轮询。

## 安全架构

```mermaid
graph TB
    CLIENT[客户端] -->|HTTPS| LB[负载均衡器 / Ingress]
    LB --> GW[Settlement :4003]

    subgraph 认证管道
        GW --> CSRF[CSRF 检查]
        CSRF --> JWT[JWT 验证<br/>HttpOnly Cookie]
        JWT --> BL[Token 黑名单<br/>Redis]
        BL --> RBAC[RequirePermission<br/>ETS 缓存]
        RBAC --> RATE[速率限制器<br/>Redis Token Bucket]
        RATE --> IDEMP[幂等性<br/>Redis]
    end

    subgraph BACEN mTLS
        DICT_S[Dict Service] -->|ICP-Brasil mTLS| BACEN[BACEN RSFN]
        SPI_S[SPI Service] -->|ICP-Brasil mTLS| BACEN
    end
```

关键安全特性：
- **认证**：RSA-OAEP 加密登录、HttpOnly JWT cookies、CSRF 双提交
- **MFA**：TOTP 及备用码
- **RBAC**：ETS 缓存的权限检查 (5 分钟 TTL)，检查 `monetarie_auth.group_features`
- **速率限制**：Redis token bucket (每 IP 每 15 分钟 10 次登录尝试)
- **账户锁定**：10 次登录失败后自动锁定
- **Token 撤销**：登出时基于 Redis 的 JWT 黑名单
- **幂等性**：基于 Redis 的 `Idempotency-Key` 头 (24 小时 TTL，SHA-256 body 指纹)

## 预期结果

阅读本页后，您应该理解：

- 4 个 umbrella 应用如何通信
- 每个 PostgreSQL schema 和 NATS 流的作用
- 安全管道如何处理请求
- 用于弹性的监督和重启策略