# Core Banking 集成

配置 Monetarie PIX 通过 NATS JetStream 和共享 JWT 认证与 Monetarie Core Banking 平台集成。

## 前提条件

- Monetarie Core Banking 已部署并可访问
- Core 和 PIX 之间共享 NATS JetStream 集群
- 两个系统中配置了共享 JWT 密钥
- 熟悉 [NATS JetStream](./nats.md) 配置

## 架构

```mermaid
graph LR
    CORE[Core Banking] -->|NATS: monetarie.core.pix.*| PIX[Monetarie PIX]
    PIX -->|NATS: monetarie.spi.*| CORE
    PIX -->|NATS: monetarie.dict.*| CORE
    CORE -->|JWT iss:monetarie| PIX
```

## 认证

### 共享 JWT 密钥

JWT 密钥回退链确保跨服务认证：

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

Core Banking Guardian tokens（HS256，`iss: "monetarie"`）被 PIX 接受，无需 `target_system` 字段。SSO tokens（`iss: "monetarie-sso"`）仍需要 `target_system: "pix"`。

### Kubernetes Secret

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: monetarie-shared-jwt-secret
  namespace: pix
type: Opaque
stringData:
  jwt-secret: "same-value-as-core-GUARDIAN_SECRET_KEY"
```

### 本地开发

```bash
# 将 PIX JWT_SECRET 设置为 Core 的开发密钥
export JWT_SECRET="dev-only-secret-key-not-for-production"
```

## NATS 事件契约

### Core -> PIX 事件

| 主题 | Event 字段 | 处理函数 | 描述 |
|------|-----------|----------|------|
| `monetarie.core.pix.payment_request` | `payment_request` | `handle_payment_request/1` | 创建出站 pacs.008 |
| `monetarie.core.pix.return_request` | `return_request` | `handle_return_request/1` | 创建 pacs.004 退回 |
| `monetarie.core.pix.key_create` | `key_create` | `handle_key_create/1` | 通过 DICT 创建 PIX 密钥 |
| `monetarie.core.pix.key_delete` | `key_delete` | `handle_key_delete/1` | 通过 DICT 删除 PIX 密钥 |
| `monetarie.core.pix.dict_lookup` | `dict_lookup` | `handle_dict_lookup/1` | DICT 密钥查询，通过 NATS 回复 |
| `monetarie.core.pix.balance_inquiry` | `balance_inquiry` | `handle_balance_inquiry/1` | SPI 余额查询，通过 NATS 回复 |

::: warning EVENT 字段路由
NATS 有效载荷中的 `"event"` 字段是 CoreEventProcessor 的路由键。缺失或拼写错误的事件值将导致静默确认但不进行处理。
:::

### PIX -> Core 事件

在 `monetarie.spi.transaction.*` 和 `monetarie.dict.keys.*` 上发布的事件包含 Core 兼容字段：

```json
{
  "type": "transaction.settled",
  "source": "pix",
  "published_at": "2026-02-09T14:30:00Z",
  "data": { ... }
}
```

### 请求/回复（JetStream 之外）

| 主题 | 方向 | 用途 |
|------|------|------|
| `dict.lookup.request` | Core <-> PIX | DICT 密钥查询（请求/回复） |
| `dict.api.request` | Core <-> PIX | 认领/MED/违规（请求/回复） |

这些主题故意放在 JetStream 流范围之外，以避免消息被截获。

## CoreEventProcessor

`CoreEventProcessor` worker 从 `MONETARIE_CORE` JetStream 流消费：

- **批量大小**：50
- **最大并发数**：5
- **HTTP 重试**：3 次尝试，指数退避（1s、2s、4s）
- **Finch 超时**：所有到 DICT 服务的 HTTP 请求 10 秒
- **追踪传播**：`x-trace-id` 头转发到内部 HTTP 调用

## Core 团队依赖项

1. 将事件发布到 `monetarie.core.pix.*` 主题（不是 `ledger.transaction.pix*`）
2. 在 `pix` 命名空间中创建 K8s secret `monetarie-shared-jwt-secret`，值匹配
3. 验证 Core 的 PixHandler 与 PIX 事件有效载荷格式兼容（`type`、`source`、`published_at`）

## 预期结果

配置 Core Banking 集成后：

- CoreEventProcessor 从 `MONETARIE_CORE` 流消费事件
- Core 的 JWT token 被 PIX 认证管道接受
- PIX 事件以 Core 兼容的有效载荷格式发布
- DICT 查询和余额查询的请求/回复正常工作