# Pacifica 连接器接口规范

> 覆盖 REST / WebSocket 端点、鉴权、错误处理以及调度策略，为 `packages/connectors/pacifica` 的实现提供统一参考。

---

## 1. REST API

| 功能 | Method | Path | 关键参数 | 返回值 (JSON) | 说明 |
|------|--------|------|----------|----------------|------|
| 查询合约配置 | `GET` | `/products/{symbol}` | `symbol` | `tickSize`, `lotSize`, `minOrderSize`, `maxLeverage` | 启动时拉取一次，落盘缓存 |
| 查询余额 | `GET` | `/account/balances` | `subaccount` | `[{ asset, available, total, equity }]` | 按账户区分，聚合至 RiskEngine |
| 查询持仓 | `GET` | `/account/positions` | `account`, `subaccount` | `[{ symbol, base, quote, entryPrice, pnl }]` | 每次下单或定时刷新 |
| 新建订单 | `POST` | `/orders/create` | `symbol`, `side (bid/ask)`, `price`, `amount`, `tif`, `postOnly`, `clientOrderId`, `account`, `subaccount?` | `{ orderId }` | `clientOrderId` 由 Router 生成，需幂等 |
| 批量撤单 | `POST` | `/orders/cancel` | `orderIds[]` 或 `clientOrderIds[]` | `{ cancelled: string[] }` | 对 Kill-switch、重置网格使用 |
| 订单列表 | `GET` | `/orders` | `symbol`, `status`, `limit` | `[{ orderId, status, filledSize, avgPrice }]` | 同步本地影子簿 |
| 成交列表 | `GET` | `/fills` | `symbol`, `since` | `[{ orderId, tradeId, price, size, fee, liquidity }]` | 对账或调试 |
| 资金费率 | `GET` | `/funding/{symbol}` | `symbol` | `{ rate, markPrice, timestamp }` | HedgeEngine / FundingMonitor 使用 |

### 1.1 请求与签名

```text
Header:
  X-Pacific-Key: <account_address>
  X-Pacific-Timestamp: <epoch_ms>
  X-Pacific-Signature: <ed25519_signature_base64>

Signature base string = `${timestamp}:${method}:${path}:${body || ''}`
signature = sign_ed25519(private_key, base_string_bytes)
```

- `<account_address>` 为 Pacifica 账户地址（原文档中称 `api_key`），与 `config.accounts.*.address` 一致。
- `timestamp` 精度毫秒，容忍 ±5 秒；偏差超出将返回 `401`。
- `body` 需按原始 JSON 字符串序列化（不去空格）；GET、DELETE 无 body 也需保留空字符串。
- 提供单元测试覆盖：空 body、数组体、浮点数序列化。

### 1.2 限频与退避

| 端点 | 限速 | 退避策略 |
|------|------|----------|
| 下单/撤单 | 60 req/min | 429 → 100ms 起步指数退避 (×2)，最多 5 次 |
| 查询类 | 120 req/min | 429 → 200ms 固定延迟，最多 3 次 |
| 资金费率 | 10 req/min | 429 → 1s 固定延迟，放弃超过 3 次 |

- 所有调用统一写入 metrics：`pacifica_rest_requests_total{endpoint, status}` 与 `pacifica_rest_latency_ms`。
- 超过最大重试次数时抛出自定义错误 `PacificaRateLimitError`，由上层降级策略处理。

### 1.3 错误码映射

| HTTP 状态 | Pacifica 错误码 | 含义 | 处理建议 |
|-----------|-----------------|------|----------|
| 400 | `INVALID_SIZE` | 订单尺寸不符合 tick/lot | 记录告警，阻止重试 |
| 400 | `POST_ONLY_WOULD_CROSS` | Post-only 订单会吃单 | Router 调整价差或放弃 |
| 401 | `UNAUTHENTICATED` | 签名/时间戳错误 | 立即 Halt 账户，通知运维 |
| 404 | `ORDER_NOT_FOUND` | 撤单目标不存在 | 视为成功，更新本地缓存 |
| 409 | `DUPLICATE_CLIENT_ID` | clientId 重复 | Router 重新生成 ID 重试一次 |
| 429 | `RATE_LIMITED` | 超限 | 按退避策略重试 |
| 500 | `INTERNAL_ERROR` | 服务异常 | 快速重试 3 次，仍失败上报 |

---

## 2. WebSocket API

### 2.1 连接与鉴权

```json
{
  "op": "login",
  "args": {
    "key": "<account_address>",
    "timestamp": "<epoch_ms>",
    "signature": "<ed25519_signature_base64>"
  }
}
```

- 连接 URL：`wss://ws.pacifica.fi/ws`
- 心跳：客户端每 30 秒发送 `{"op":"ping"}`，收到 `{"op":"pong"}`；10 秒内无响应视为断线。
- 断线重连需回放增量：`lastSeq` 由订阅回调附带，重连时通过 `{"op":"subscribe","channel":"orders","lastSeq":12345}`。

### 2.2 订阅频道

| 频道 | 事件结构 | 说明 |
|------|----------|------|
| `book.{symbol}` | `{ seq, bids:[[px,sz],...], asks:[], ts }` | 影子订单簿、延迟监控 |
| `trades.{symbol}` | `{ seq, side, price, size, tradeId, ts }` | 剥头皮信号、回测 |
| `orders.{subaccount}` | `{ seq, orderId, clientId, status, filled, remaining, avgPrice, ts }` | 同步本地状态 |
| `fills.{subaccount}` | `{ seq, orderId, tradeId, price, size, fee, liquidity, ts }` | GridMaker / Scalper onFill |
| `account.{subaccount}` | `{ seq, balances:[...], positions:[...] }` | 风控快照 |

### 2.3 消息处理规范

1. 依据 `seq` 单调递增校验；出现跳号立即触发 full snapshot。
2. 所有事件写入 `events.log`（用于回放），并发送到内存事件总线。
3. WS 错误回执：
   ```json
   { "op":"error", "code":"RATE_LIMITED", "message":"..." }
   ```
   - `RATE_LIMITED` → 立刻退订 5 秒，重订。
   - `AUTH_FAILED` → 触发 Kill-switch。

### 2.4 重连策略

```mermaid
flowchart TD
    A[连接断开] --> B{重试次数 < 5?}
    B -- 是 --> C[等待 backoff (0.5s × 2^n)]
    C --> D[重连 → login → resubscribe]
    D -->|成功| E[恢复]
    D -->|失败| B
    B -- 否 --> F[触发 HALT + 告警]
```

---

## 3. 调用封装约定

- 所有 REST 请求均通过 `PacificaHttpClient`，统一附加签名、限频控制、日志。
- WS 由 `PacificaWebSocket` 封装，提供：
  - `subscribe(channel, handler)`
  - `unsubscribe(channel)`
  - `onReconnect(cb)`：用于重新分发共享 socket。
- Adapter 暴露 Promise API，错误以自定义错误类区分：
  - `PacificaValidationError`
  - `PacificaRateLimitError`
  - `PacificaAuthError`
  - `PacificaUnavailableError`

---

## 4. 监控指标

| 指标 | 标签 | 含义 |
|------|------|------|
| `pacifica_rest_requests_total` | `endpoint`, `status` | REST 请求计数 |
| `pacifica_rest_latency_ms_bucket` | `endpoint` | REST 延迟直方图 |
| `pacifica_ws_events_total` | `channel`, `type` | WS 事件数量 |
| `pacifica_ws_reconnects_total` |  | 重连次数 |
| `pacifica_ws_gaps_total` | `channel` | 序列号断层次数 |

报警建议：
- 5 分钟内 `pacifica_ws_reconnects_total` 增长 > 3：触发网络告警。
- `pacifica_rest_requests_total{status="429"}` 连续 10 次：提示策略降频。

---

## 5. 集成清单

- [ ] `signing.ts` 单元测试覆盖空 body、有序列化差异、错误私钥。
- [ ] REST/WS 客户端具备重试、限流、断线恢复。
- [ ] 统一错误码映射并接入降级策略。
- [ ] Prometheus 指标注册并在 `Telemetry` 包内导出。
- [ ] 文档随 API 变化更新版本号。
