# 架构详情

FluxiQ PIX 架构的深入技术参考，涵盖监督树、进程生命周期和内部通信模式。

## 前提条件

- 深入了解 Elixir/OTP 概念
- 熟悉 GenServer、Supervisor 和 Application 模式
- 了解[架构概览](../guide/architecture.md)

## 应用启动序列

```mermaid
sequenceDiagram
    participant OS
    participant BEAM
    participant Shared
    participant Dict
    participant SPI
    participant Settlement

    OS->>BEAM: 启动 release
    BEAM->>Shared: Application.start/2
    Shared->>Shared: PostgrexSupervisor, Repo, Finch, Redis, CertificatePool, ChannelRouter, ErrorLookup, PartitionManager
    Shared->>Shared: NATS Supervisor (如果 NATS_ENABLED)
    Shared->>Shared: Simulator GenServer (如果 SIMULATOR_ENABLED)
    BEAM->>Dict: Application.start/2
    Dict->>Dict: Endpoint :4001, CidSyncService, NatsPublisher
    BEAM->>SPI: Application.start/2
    SPI->>SPI: Endpoint :4002, Workers Supervisor
    BEAM->>Settlement: Application.start/2
    Settlement->>Settlement: Endpoint :4003, Workers Supervisor, Broadcaster, HealthChecker, QueueMonitor
```

## 监督树（详细）

### Shared.Application

```
Shared.Application (one_for_one, max_restarts: 10/60s)
├── Shared.PostgrexSupervisor
├── Shared.Repo
├── {Finch, name: Shared.Finch}
│   ├── DICT 连接池 (10 x 2 = 20 连接)
│   └── 默认连接池 (25 x 2 = 50 连接)
├── Shared.Telemetry
├── Shared.Redis.Connection (10 连接池, 5s 超时)
├── Shared.Crypto.CertificatePool (5 分钟刷新)
├── Shared.Bacen.ChannelRouter (健康追踪)
├── Shared.Bacen.ErrorLookup (10 分钟 ETS 刷新)
├── Shared.Nats.Supervisor (条件: NATS_ENABLED=true)
├── Shared.Bacen.Simulator (条件: SIMULATOR_ENABLED=true)
└── Shared.Audit.PartitionManager (每日检查 + 清除)
```

### SpiService.Application

```
SpiService.Application (rest_for_one, max_restarts: 10/60s)
├── SpiServiceWeb.Endpoint (:4002)
└── SpiService.Workers.Supervisor (条件: NATS_ENABLED=true, max_restarts: 10/60s)
    ├── InboundProcessor (batch: 100, concurrency: 10)
    ├── OutboundSender (batch: 100, concurrency: 10)
    ├── ReturnProcessor (batch: 100, concurrency: 5)
    └── StatusUpdater (batch: 100, concurrency: 10)
```

### SettlementService.Application

```
SettlementService.Application (rest_for_one, max_restarts: 10/60s)
├── SettlementServiceWeb.Endpoint (:4003)
├── SettlementService.Workers.Supervisor (条件: NATS_ENABLED=true, max_restarts: 10/60s)
│   ├── Scheduler (LIMIT 500K, 30s 超时)
│   ├── FileImporter
│   └── CoreEventProcessor (batch: 50, concurrency: 5, HTTP 重试: 3x 退避)
├── SettlementService.Monitoring.Broadcaster (PubSub 事件)
├── SettlementService.Monitoring.HealthChecker (10s/30s 检查)
└── SettlementService.Monitoring.QueueMonitor (15s NATS 延迟)
```

## ETS 表

| 表 | 模块 | 用途 | 选项 |
|----|------|------|------|
| `:circuit_breaker_state` | CircuitBreaker | 断路器状态 | `write_concurrency: true` |
| `:rbac_cache` | RequirePermission | 权限缓存（5 分钟 TTL） | `read_concurrency: true` |
| `:error_lookup` | ErrorLookup | BACEN 错误码（10 分钟 TTL） | `read_concurrency: true` |

## 请求管道（Settlement）

```
客户端请求
  → Plug.SSL (HTTP 重定向到 HTTPS)
  → Plug.RequestId (分配请求 ID)
  → TraceContext (生成/提取 x-trace-id)
  → Plug.Parsers (JSON 请求体解析)
  → Router
    → :gateway 管道
      → CSRF 验证
      → JWTAuth (Cookie 提取, 黑名单检查)
      → RequirePermission (ETS 缓存 RBAC)
    → :idempotent 管道 (POST /payments, /transactions)
      → Idempotency 插件 (Redis SET NX)
    → Controller
      → InternalClient (断路器 + 追踪传播)
      → Repo (Ecto 查询)
      → NATS publish (如适用)
  → 响应 (JSON, camelCase 序列化)
```

## 断路器状态机

```mermaid
stateDiagram-v2
    [*] --> Closed
    Closed --> Open: 5 次失败
    Open --> HalfOpen: 30s 冷却
    HalfOpen --> Closed: 探测成功
    HalfOpen --> Open: 探测失败
```

- 使用原子 `:ets.update_counter/4` 进行线程安全的失败计数
- 仅 5xx 和传输错误触发断路器
- 半开状态下单次探测请求

## Finch 连接池

| 目标 | 池大小 | 数量 | 总计 |
|------|--------|------|------|
| DICT 服务 | 10 | 2 | 20 |
| 默认 | 25 | 2 | 50 |

## BaseWorker 生命周期

```mermaid
stateDiagram-v2
    [*] --> Init: start_link
    Init --> CheckNATS: init/1
    CheckNATS --> Idle: NATS 已禁用
    CheckNATS --> Subscribe: NATS 已启用
    Subscribe --> Poll: 消费者已创建
    Poll --> Process: 有可用消息
    Process --> ACK: 成功
    Process --> NAK: 暂时性错误
    Process --> DLQ: 超过最大重试次数
    ACK --> Poll: 下一批
    NAK --> Poll: 稍后重试
    DLQ --> Poll: 丢弃消息
```

## 预期结果

阅读本参考后：

- 完全了解应用启动序列
- 详细了解监督树和重启策略
- 了解 ETS 表及其一致性模型
- 请求管道从入口到响应
- 断路器和 Worker 生命周期状态机