grid_skeleton/docs/ARCHITECTURE_DESIGN.md

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，避免单账户误杀
  • 多维度熔断触发器：
  • PnL 回撤超阈值（-0.5%）
  • Delta 绝对值失控（>2x max_base_abs）
  • 连续对冲失败次数 >3
  • 行情数据断流 >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 中说明影响。