# Pacifica Delta-Neutral 策略架构设计

## 1. 设计目标
- 在 **Delta≈0** 约束下，通过被动做市与微剥头皮捕捉点差、Maker 返佣与短期均值回归收益。
- 全链路符合交易场所及监管要求：自成交预防、可审计日志、风控优先。
- 模块化 TypeScript 架构，可在实盘/回测之间复用同一套策略逻辑，支持多 venue 扩展与持续运维。

### 1.1 文档遵循
- 架构实施需与以下详细规范保持一致，任何偏离必须先更新对应文档并获评审认可：
  - `docs/API_CONNECTOR_SPEC.md`：连接层端点、签名与错误处理
  - `docs/MODULE_INTERFACES.md`：模块接口、依赖图与错误类型
  - `docs/SEQUENCE_FLOW.md`：行情、策略、执行、对冲、降级的时序
  - `docs/CONFIG_REFERENCE.md`：配置字段、默认值与热更新策略
  - `docs/TESTING_PLAN.md`：测试矩阵、验收指标
  - `docs/OPERATIONS_PLAYBOOK.md`：运维巡检、降级和恢复流程
- 代码实现、配置模板、测试计划及运维脚本发生变更时，需同步更新以上文档并在 PR 中引用。

## 2. 总体架构
```
┌───────────────────────────────────────────────────────────────┐
│                         Apps / Runners                        │
│  - live-runner  - canary-runner  - replay-runner (backtest)   │
└────────────┬─────────────────────────────┬────────────────────┘
             │                             │
      ┌──────▼────────┐            ┌───────▼───────────────────┐
      │ Strategy Bus  │            │ Risk & Compliance Engine │
      │ (MM, Scalper, │            │ (limits, STP, kill-switch│
      │ ExecutionPolicy)│          │ audit, policy gating)    │
      └─────┬──────────┘            └─────────┬────────────────┘
            │                                   │
     ┌──────▼─────────┐                  ┌──────▼───────────┐
     │ Order Router   │◄────Health──────►│ Telemetry & Logs │
     │ (child orders, │                  │ (Prom, Pino,     │
     │ slippage guard)│                  │  audit trail)    │
     └─────┬──────────┘                  └──────┬───────────┘
           │                                   │
   ┌───────▼──────────┐            ┌───────────▼──────────────┐
   │ Exchange Adapter │◄──────────►│ Market Data Pipeline     │
   │ (Pacifica, +N)   │ (WS/REST)  │ (shadow book, derived
data)│
   └────────┬─────────┘            └───────────┬──────────────┘
            │                                  │
      ┌─────▼──────────┐              ┌────────▼───────────┐
      │ Persistence    │              │ Backtest/Simulator │
      │ (PnL, fills,   │              │ (event replay, fee│
      │ configs, audit)│              │ model)             │
      └────────────────┘              └────────────────────┘
```

**架构优化说明**（2025-10 更新）：
- 新增 **Symbol Registry & Allocator**：管理多标的生命周期，动态分配全局风险预算
- 新增 **Global Order Coordinator**：跨账户 STP 检查，防止关联账户间的经济自成交
- 新增 **Strategy Coordinator**：协调 MM 和 Scalper 信号，避免方向冲突和重复对冲成本
- Exchange Adapter 支持多账户（Account A/B）管理，实现跨账户对冲
- Market Data Pipeline 增强延迟追踪，支持回测延迟注入防止前瞻偏差

## 3. 模块分解
### 3.1 App Runner 层
- `apps/runner`: 负责 DI 容器、配置加载与热更新、生命周期管理（启动、平滑关闭）。
- 提供 `live-runner`、`canary-runner`、`replay-runner` 三种应用入口，统一注入策略与引擎。

### 3.2 配置与密钥管理
- `.env`：API base、key、Ed25519 私钥、子账户等敏感信息。
- `config/config.yaml`：策略参数（symbols、mm、scalper、risk、hedge、telemetry），通过 `zod` 校验与热更新。
- 配置更新事件写入审计表，支持回滚与差异比对。

### 3.3 Symbol Registry & Allocator（`packages/registry`，新增）
- 动态管理多标的（BTC/ETH/SOL 等）的启动、暂停、卸载生命周期
- 全局风险预算分配：将总名义上限、回撤阈值按标的流动性与相关性分配
- 标的间相关性监控：检测多标的同时持仓时的隐性风险暴露
- 自动标的筛选器：基于流动性、spread、funding rate 相关性评分，动态启用/禁用标的
- 配置热更新时，协调各标的策略实例的参数同步

### 3.4 Global Order Coordinator（`packages/execution/globalCoordinator.ts`，新增）
- **跨账户订单注册表**：维护所有账户/venue 的挂单镜像（clientId + account + symbol + side + px）
- **跨账户 STP 检查**：
  - 在任一账户下单前，检查对手价是否来自关联账户的挂单
  - 若是对冲单（由 HedgeEngine 标记），允许跨账户匹配
  - 若是策略单（MM/Scalper），拒绝经济自成交
- **订单冲突检测**：检测同一标的上多个策略的订单是否方向相反或价格重叠
- **降级策略触发**：当检测到异常（如单账户延迟过高、对冲失败率>阈值），触发该账户的降级模式

### 3.5 Strategy Coordinator（`packages/strategies/coordinator.ts`，新增）
- **信号聚合与冲突解决**：
  - MM 和 Scalper 提交"意向订单"（intent）而非直接下单
  - 检测同一标的上的方向冲突（如 MM sell + Scalper buy）
  - 冲突解决策略：优先级（MM > Scalper）、合并同向订单、取消相反订单
- **净仓位变化输出**：将多个策略的意向订单合并为"净仓位变化"，避免对冲引擎频繁触发
- **策略隔离模式**：当某策略表现劣化（EV < 0 持续 N 分钟），自动暂停该策略
- **全局冷却管理**：跨策略的订单频率限制，避免触发 venue 限频

### 3.6 Exchange Adapter（`packages/connectors/pacifica`）
- `adapter.ts`：封装 REST 请求（下单、撤单、批量撤、持仓、资金费率、账户信息）。
- `signing.ts`：Ed25519 签名实现（确定性 JSON 序列化、时间戳、header 注入）。
- 限频器（token bucket）与重试策略，统一错误码映射。
- **多账户支持**（优化）：每个 adapter 实例绑定一个账户（address + subaccount），通过 `adapterRegistry` 管理 Account A/B。
- **对冲延迟追踪**（优化）：记录每笔对冲单从发起到成交的延迟，暴露 P50/P95/P99 指标。

### 3.7 市场数据管线（`packages/utils/shadowBook.ts`, `packages/utils/marketDataAdapter.ts`）
- 订阅 REST/WS 行情，合并增量，维护影子订单簿与本地时间戳；市场数据适配器负责定期刷新快照并推送事件。
- 提供派生特征：`mid`、`spread_bps`、`order_book_imbalance(k)`、短时波动率 `rv`、队列估算 `queue_alpha`。
- 对数据断流进行健康检查，异常时触发风险引擎 HALT。

### 3.8 Execution / Order Routing（`packages/execution/orderRouter.ts`）
- 对外接受策略订单（limit/IOC/FOK/postOnly/OCO 子单），路由至指定 adapter。
- 包含滑点守卫（对比影子簿 top of book）、`clientId` 去重、STP 检查（不得与本地挂单交叉）。
- 提供批量撤单、定时补单、状态回调接口。

### 3.9 Risk & Compliance（`packages/risk`）
- `RiskEngine`: 名义/库存/单笔上限，订单前置校验；实时记录 realized PnL，触发回撤熔断。
- **Kill-switch（增强）**：
  - **跨账户聚合模式**：计算 Account A + Account B 的总权益与总 PnL，避免单账户误杀
  - **多维度熔断触发器**：
    1. PnL 回撤超阈值（-0.5%）
    2. Delta 绝对值失控（>2x max_base_abs）
    3. 连续对冲失败次数 >3
    4. 行情数据断流 >3 秒
  - **时间窗口回撤**：基于滑动窗口（如 1 小时）计算回撤，而非从启动时刻开始
- 审计模块：记录信号、决策、风控审批、下单、成交、对冲全过程（trace id）。

### 3.10 策略层（`packages/strategies`）
- `MarketMaker`: 按 mid±δ 多层挂单；基于波动 regime 调整 spread/clip/reprice 周期。
- `MicroScalper`: spread 扩张 + 成交流不平衡触发；以 `ExecutionPolicy` 决定被动/主动模式、tp/sl 目标。
- **`GridMaker`（新增，备选策略）**：
  - 在价格区间内均匀分布买卖订单网格，捕捉震荡市往返价差
  - 买单成交 @ price_buy → 在 price_buy * (1 + grid_step) 挂卖单
  - 卖单成交 @ price_sell → 在 price_sell * (1 - grid_step) 挂买单
  - 批量对冲：Delta 累积到阈值（如 0.3 BTC）触发对冲引擎
  - 自适应调整：价格偏离网格中心 >2% 时，撤旧单重新布网格
  - 趋势检测：1 小时涨跌 >0.5% 时自动暂停，避免单边持仓
  - **优势**：实现简单（200 行）、对冲频率低（2-5 次/小时 vs 剥头皮 10-20 次）、参数稳定
  - **适用场景**：震荡市、高波动低趋势、DEX 高延迟环境
  - **策略切换**：通过 `config.yaml` 中的 `strategy_mode: grid | scalper | both` 选择
- 通过 `StrategyBus` 协调执行节奏，避免信号竞态；支持启停、参数热更。
- **策略协调器（混合模式）**：当 `strategy_mode=both` 时，GridMaker 和 Scalper 通过优先级避免冲突（网格优先，剥头皮仅在极端 spread 触发）。

### 3.11 对冲与仓位管理（`packages/portfolio`, `packages/hedge`）
- `PositionManager`: 聚合多 venue/子账户仓位、计算净 Delta、资金费暴露。
- `HedgeEngine`: PI 控制器计算对冲量，强制最小间隔，调用对冲 venue 的 IOC/紧限价单；记录 hedge 成本。
- **对冲延迟预算模型（新增）**：
  - 目标：对冲延迟 P50 < 500ms, P99 < 2s
  - 超时处理：若对冲未在 3 秒内完成，触发强制市价平仓
  - 对冲失败重试：最多重试 2 次，每次增加滑点容忍度 +5bps
- **资金费率套利风险监控（新增）**：
  - 监控双账户所在 venue 的 funding rate 相关性
  - 若相关性 < 0.8 或同向支付，告警并建议减仓
- 支持资金费率偏置（当期 funding 不利时主动减仓）。

### 3.12 TriggerEngine（`packages/execution/triggerEngine.ts`）
- 管理 OCO 止盈止损、时间止损、离散触发器；确保与 RiskEngine/OrderRouter 共用校验路径。

### 3.13 Telemetry & Logging（`packages/telemetry`）
- `prom-client` 暴露指标：`maker_ratio`, `avg_edge_bps`, `real_slip_bps`, `delta_abs`, `hedge_cost_bps`, `latency_p99`, `cancel_rate`, `pnl_intraday`, `stp_hits` 等。
- **对冲效率指标（新增）**：
  - `hedge_success_rate`: 对冲订单成交率（目标 >98%）
  - `hedge_latency_p50/p95/p99`: 从信号到对冲完成的延迟分位数
  - `hedge_slippage_bps`: 对冲实际成交价 vs 预期价的偏差
  - `cross_venue_basis_bps`: 双账户所在 venue 的价差，用于发现套利机会或数据异常
- `pino` 结构化日志 + `pino-pretty` 本地调试；审计日志写入 append-only 存储（文件或数据库）。
- 与报警系统联动（Grafana/Loki/Slack Webhook）。

### 3.14 Persistence（可插拔）
- 初期：本地文件或 SQLite 记录 fills、PnL、配置历史、审计日志。
- 扩展：接入云数据库（PostgreSQL/ClickHouse）用于长周期分析与回测数据管理。

### 3.15 Backtest / Simulator (`packages/backtest`)
- 事件重放：对实时 `MarketDataEvent` 与 `OrderEvent` 进行回放，驱动同一套策略模块。
- **延迟注入模块（新增）**：
  - 记录实盘"链上事件时间 vs 策略接收时间"的延迟分布
  - 回测时按真实延迟分布注入随机延迟，防止前瞻偏差
  - 验证：回测 Sharpe 应略低于实盘（若高于则存在数据泄漏）
- 手续费/滑点模型、资金费率模型注入；输出报表与 KPI。
- 支持参数搜索、策略回测对比、敏感性分析。

## 4. 数据与控制流（增强版）
1. **行情路径**：
   - Multi-venue Adapter 拉取/订阅 → 各 ShadowBook 实例更新 → Derived metrics (OBI/RV/spread)
   - → Symbol Registry 聚合 → Strategy Bus 消费 → 策略生成意向订单

2. **订单路径（协调版）**：
   - 策略（MM/Scalper）发出 intent → **Strategy Coordinator 冲突检测与合并**
   - → **Global Order Coordinator 跨账户 STP 检查**
   - → RiskEngine 审批（限额/kill-switch）
   - → OrderRouter 发单（滑点守卫）→ Adapter 执行
   - → Fill/PnL 回流 RiskEngine/Telemetry + PositionManager

3. **对冲路径（增强版）**：
   - Fill 触发 → PositionManager 更新净仓（跨账户聚合）
   - → HedgeEngine 计算对冲量（PI 控制器 + 延迟预算检查）
   - → 对冲 venue IOC 单（带重试机制）
   - → 结果回写（成功/失败/延迟）→ Telemetry 记录对冲成本与延迟
   - → 若失败次数 >3，触发 Global Order Coordinator 降级策略

4. **监控路径**：
   - 各模块推送指标/日志（含对冲效率指标）→ Telemetry 聚合
   - → Dashboard/报警系统处理 → 触发降级或 kill-switch

5. **配置热更（金丝雀流程）**：
   - 配置变更请求 → zod 校验 + 回测烟囱测试
   - → 金丝雀（单标的试运行 10 分钟）→ KPI 验证
   - → 若达标则全量发布，否则自动回滚
   - → 全程审计日志记录（who/when/what/result）

6. **降级路径（新增）**：
   - 异常检测（对冲失败/延迟过高/数据断流）→ Global Order Coordinator 触发
   - → 根据降级矩阵执行（撤单/只平不开/暂停策略/HALT）
   - → 告警推送 + 审计日志

## 5. 合规与风控设计
- **STP（增强）**：
  - 单账户内 STP：Router 前置自查，避免与本地挂单交叉
  - 跨账户经济 STP：Global Order Coordinator 检查对手价是否来自关联账户
  - 对冲例外：对冲单允许跨账户匹配，但需明确标记
- **风险限额**：订单前置、仓位持续监控、跨账户聚合 PnL 回撤 Kill-switch、外部命令可触发 HALT。
- **审计**：所有决策节点生成唯一 trace id，写入 append-only 日志，含参数版本、行情快照摘要。
- **操作规范**：禁止主动制造虚假成交量，策略仅在合规 venue 与账户运行。

## 5.5 降级策略矩阵（新增）

| 故障场景                  | 检测条件                              | 降级动作                                    | 恢复条件                |
|--------------------------|--------------------------------------|-------------------------------------------|------------------------|
| 主账户行情断流            | >5s 无行情更新                        | 撤主账户所有挂单，保留对冲账户               | 行情恢复且延迟 <500ms   |
| 对冲账户 API 故障          | 连续 3 次对冲失败                     | 主账户切换为"只平不开"模式                   | 对冲账户恢复正常 5 分钟 |
| 双账户都断流              | 双重断流 >3s                          | 全部撤单 + HALT + 告警                      | 手动恢复                |
| 对冲延迟过高              | hedge_latency_p95 > 2s 持续 1 分钟   | 暂停新信号，仅处理存量仓位                   | 延迟降至 <1s            |
| Gas fee 暴涨（链上 DEX）  | 对冲成本 > edge_bps * 2               | 暂停新信号，延长对冲间隔至 1 分钟            | Gas 降至正常水平        |
| Delta 失控                | abs(delta) > 2x max_base_abs          | 强制市价对冲，暂停所有策略 1 分钟            | Delta 归零              |
| Funding rate 异常         | 双 venue funding rate 相关性 <0.5     | 减仓至 50%，告警通知人工审查                | 人工确认后恢复          |
| 策略表现劣化              | 某策略 EV <0 持续 10 分钟             | 自动暂停该策略，保留其他策略运行             | 参数调整后手动启用       |
| 跨账户 STP 命中率过高     | STP 拒绝率 >5%                        | 暂停 Scalper，仅保留 MM                     | STP 率 <1% 持续 5 分钟  |

**降级策略实现要点**：
- 所有降级动作触发时，立即写入审计日志并推送告警（Slack/PagerDuty）
- 降级状态持久化到配置文件，重启后保留降级状态
- 提供手动干预接口：`/api/override-degradation`（需认证）

## 6. 部署与运维
- Node 22 + pnpm；容器化（Docker）部署到 Kubernetes/自管主机。
- 热更：配置文件挂载 + SIGHUP 触发重载；策略参数金丝雀发布。
- 健康检查：Adapter 连通性、行情延迟、PnL drawdown、STP 命中频次。
- Playbook：冷启动、波动骤升、数据断流、对冲失败、资金费率极端等场景演练。

## 7. 技术栈与依赖
- 语言/构建：TypeScript 5、pnpm、ts-node/tsx。
- 网络：`undici`, `ws`；加密：`@noble/ed25519`。
- 校验：`zod`；配置：`dotenv`, `cosmiconfig`。
- 日志：`pino`, `pino-pretty`；指标：`prom-client`。
- 测试：`vitest`/`jest` + 自定义事件回放框架。

## 8. 运行时序示例
1. **MarketMaker 定时循环**
   - `StrategyBus` 触发 `MarketMaker.onTimer` → ShadowBook 提供 mid/spread → 生成双边限价单 → RiskEngine 校验 → OrderRouter(postOnly) 下单 → Telemetry 记录。
2. **Scalper 行情触发**
   - `ShadowBook` 发布新行情 → `MicroScalper.onBook` 检测 spread 扩张 → 发起 taker/被动组合 → TriggerEngine 设置 OCO → OrderRouter 执行。
3. **对冲**
   - Fill 事件回写 → PositionManager 更新净仓 → HedgeEngine PI 计算 → RiskEngine 审批 → 对冲 Adapter IOC → Telemetry 记录成本。
4. **Kill-Switch**
   - RiskEngine 监测 PnL drawdown/数据断流 → 触发 HALT → Router 撤单、策略暂停、报警推送。

## 9. 测试与质量保障
- 单元测试：签名、影子簿、风控、策略决策函数。
- 集成测试：模拟行情流 + 订单回执，验证完整链路。
- 回测：在 CI 中跑缩短数据集作为烟囱测试；PR 需附回测 KPI。
- 覆盖率与代码质量：ESLint、Prettier、TypeDoc 文档生成。

## 10. 迭代路线
- 与 `docs/IMPLEMENTATION_PLAN.md` 里程碑保持同步，每阶段结束更新本架构文档状态。
- 记录关键设计变更（如新 venue、风险策略调整）并在 PR 中说明影响。