OKX 网格交易策略 — 架构文档

一、模块总览

okxNewPrice/
├── OkxConfig.java              # 全局配置（Builder模式）
├── OkxGridTradeService.java    # 核心策略引擎
├── OkxTradeExecutor.java       # REST API 异步执行器
├── OkxGridElement.java         # 网格价格层级 + 8个全局O(1)索引
├── OkxTraderParam.java         # 单笔挂单参数
├── OkxGridWsClient.java        # WebSocket 客户端（双连接）
├── OkxWebSocketClientManager.java  # Spring容器入口 + WS组装
├── ExchangeInfoEnum.java       # 账户枚举
│
├── gridWs/
│   ├── OkxGridChannelHandler.java       # 频道处理器接口
│   ├── OkxKlineChannelHandler.java      # candle1m → onKline()
│   ├── OkxPositionsChannelHandler.java  # positions → onPositionUpdate()
│   ├── OkxOrdersChannelHandler.java     # orders → onOrderUpdate()（替代orders-algo）
│   └── OkxAlgoOrdersChannelHandler.java # orders-algo（测试网不可用，保留备用）
│
└── okxpi/config/              # OKX API 底层HTTP/签名工具

二、策略生命周期

┌─────────────────────────────────────────────────────────────────┐
│  init() → startGrid() → WAITING_KLINE                          │
│    ↓                                                            │
│  onKline(首根K线) → OPENING → 市价双开基底                      │
│    ├── openLong(baseQuantity张)                                 │
│    └── openShort(baseQuantity张)                                │
│    ↓                                                            │
│  onPositionUpdate() → 双基底成交 → tryGenerateQueues()          │
│    ├── generateShortQueue()   空仓队列（基准价向下步进）         │
│    ├── generateLongQueue()    多仓队列（基准价向上步进）         │
│    ├── updateGridElements()   构建OkxGridElement双向链表         │
│    ├── 多仓止损 -2~-11: algo(sell+long, slTriggerPx, sz=qty)   │
│    └── 空仓止损  2~11: algo(buy+short, slTriggerPx, sz=qty)    │
│    ↓                                                            │
│  state = ACTIVE                                                 │
└─────────────────────────────────────────────────────────────────┘

状态机

三、WS连接架构

┌──────────────────────────────────────────────────────┐
│  OkxWebSocketClientManager (@PostConstruct)           │
│                                                       │
│  ┌─ gridWsClientPublic ───────────────────────────┐  │
│  │  URL: /ws/v5/business  (无需登录，直连订阅)     │  │
│  │  ├── OkxKlineChannelHandler (candle1m)          │  │
│  └────────────────────────────────────────────────┘  │
│                                                       │
│  ┌─ gridWsClientPrivate ──────────────────────────┐  │
│  │  URL: /ws/v5/private  (先登录再订阅)           │  │
│  │  ├── OkxPositionsChannelHandler (positions)     │  │
│  │  └── OkxOrdersChannelHandler (orders)           │  │
│  └────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────┘

注意：orders-algo 频道在测试网不可用（60018），已替换为 orders 频道。algo触发后生成普通订单，fill数据中带 algoId 字段可匹配回原始条件单。

四、网格ID体系

价格方向：  低 ←────────────────── 基准价 ──────────────────→ 高
ID:        -N ... -3  -2  -1    0    1   2   3 ... N
用途:      多仓止损区           基底     空仓止损区
           (初始化: -2~-11)           (初始化: 2~11)

链表: ... ← -3 ← -2 ← -1 ← 0 → 1 → 2 → 3 → ...
         (通过 upId/downId + INDEX 实现 O(1) 遍历)

GridElement 字段

8个全局O(1)索引

INDEX                  → findById(int)
PRICE_INDEX            → findByPrice(BigDecimal)
LONG_ORDER_ID_INDEX    → findByLongOrderId(String)
SHORT_ORDER_ID_INDEX   → findByShortOrderId(String)
LONG_TP_ORDER_ID_INDEX → findByLongTakeProfitOrderId(String)
SHORT_TP_ORDER_ID_INDEX→ findByShortTakeProfitOrderId(String)
LONG_SL_ORDER_ID_INDEX → findByLongStopLossOrderId(String)
SHORT_SL_ORDER_ID_INDEX→ findByShortStopLossOrderId(String)

五、事件驱动循环（ACTIVE状态）

5.1 K线回调 onKline(closePrice)

更新 lastKlinePrice → updateUnrealizedPnl()
→ STOPPED: 清条件单+平仓+startGrid()
→ WAITING_KLINE: 市价双开基底
→ ACTIVE: checkProfitAndReset()（每根K线检查盈亏达标）

5.2 仓位推送 onPositionUpdate(instId, posSide, posSize, avgPx)

基底首次成交 → tryGenerateQueues()
后续仓位变化 → 更新 positionSize/entryPrice
仓位归零     → handlePositionZeroAndReset()

5.3 订单成交 onOrderUpdate(algoId, state, ordType)

state == "filled" 时：

  ┌─ findByLongStopLossOrderId(algoId) → handleLongStopLossTriggered()
  │   清空止损ID → grid -(N-1) 挂 count×qty 张多单
  │              → 若 N>2, 取消 grid -(N-2) 旧多单
  │
  ├─ findByShortStopLossOrderId(algoId) → handleShortStopLossTriggered()
  │   清空止损ID → grid N-1 挂 count×qty 张空单
  │              → 若 N>2, 取消 grid N-2 旧空单
  │
  ├─ findByShortOrderId(algoId) → extendShortStopLoss(filledQty)
  │   从最远空仓止损向外扩展 stopLossCount 个网格止损
  │
  └─ findByLongOrderId(algoId) → extendLongStopLoss(filledQty)
      从最远多仓止损向外扩展 stopLossCount 个网格止损

5.4 平仓推送 onPositionClose(side, pnl)

cumulativePnl += pnl
→ 总盈亏 ≤ -maxLoss → 钉钉告警（不停止，仅通知）

六、关键公式

6.1 网格步长

step = shortBaseEntryPrice × gridRate    (对齐到 priceScale 精度)

6.2 止损触发 → 追单数量

priceDiff = |avgEntryPrice - newEntryGridPrice|.abs()
count     = priceDiff / step  (DOWN取整, 最小1)
entryQty  = count × quantity

6.3 挂单成交 → 追挂止损

stopLossCount = filledQty / quantity
从最远止损ID向外扩展 stopLossCount 个网格，每格挂 1个 quantity张的止损单

6.4 未实现盈亏

多仓Pnl = longPositionSize × ctVal × (lastKlinePrice - longEntryPrice)
空仓Pnl = shortPositionSize × ctVal × (shortEntryPrice - lastKlinePrice)
unrealizedPnl = 多仓Pnl + 空仓Pnl

6.5 盈亏达标检查

upl + availEq > initialPrincipal + expectedProfit  →  重置策略

七、REST API 映射

八、配置参数（OkxConfig.Builder默认值）

九、线程模型

WS回调线程（串行）             Executor线程（单线程池）
  │                              │
  ├─ onKline()                   ├─ openLong/openShort
  ├─ onPositionUpdate()          ├─ marketClose
  ├─ onOrderUpdate() ──下单──→   ├─ placeConditionalEntryOrder
  │                              ├─ placeTakeProfit
  │                              └─ cancelAlgoOrder
  │
  └─ checkProfitAndReset() (REST同步查余额)

• WS回调在 [ctReadThread-XX] 中**串行**执行，避免并发问题
• REST API 提交到 okx-trade-worker 单线程池异步执行，避免阻塞WS线程
• closeExistingPositions() 和 handlePositionZeroAndReset() 在WS线程中同步调用REST，需注意耗时
• LostConnectionChecker 已关闭（setConnectionLostTimeout(0)），由应用层 ping/pong 心跳接管