feat(gateApi): 更新网格交易逻辑文档和参数配置

Administrator

7 hours ago 2ba5828bc900a5a3646d9dfe78f53ff68e444fd4

 src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md

@@ -59,16 +59,18 @@
│       └─ gridTradeService.onKline(closePx)
│           ├─ 更新 unrealizedPnl（浮动盈亏）
│           ├─ state=WAITING_KLINE → 异步双开基底仓位
│           └─ state=ACTIVE → processShortGrid/processLongGrid 网格触发
│           └─ state=ACTIVE → 方向区分: closePrice>longPriceQueue[0]→processLongGrid,
│               closePrice<shortPriceQueue[0]→processShortGrid, 其余跳过（一个K线只触发一个方向）
│
├─ futures.positions (私有, HMAC-SHA512)
│   └─ PositionsChannelHandler
│       ├─ 解析 mode → Position.ModeEnum（DUAL_LONG / DUAL_SHORT）
│       ├─ 日志输出全部 20 个推送字段（contract/mode/size/entry_price/.../update_id）
│       └─ gridTradeService.onPositionUpdate(contract, mode, size, entryPrice)
│           ├─ 有仓位: 标记活跃，首次成交记录入场价并设止盈
│           │   ├─ 基底开仓 → 首次成交 → 记录基底入场价 → 双基底都成交后生成网格队列
│           │   └─ 网格开仓 → 成交后立即设止盈单（plan-close-*-position）
│           ├─ 有仓位: 标记活跃，首次成交记录入场价
│           │   ├─ 基底开仓 → 首次成交 → 记录基底入场价 → 双基底都成交后生成网格队列+挂限价单
│           │   └─ 网格开仓 → 仓位增加时按 quantity 为单位计算增量，逐个从止盈队列消费止盈价；
│           │       止盈队列不足时用 entryPrice ± step 兜底
│           └─ 无仓位(size=0): 标记不活跃
│
├─ futures.position_closes (私有, HMAC-SHA512)
@@ -79,6 +81,8 @@
└─ 所有下单操作
    └─ GateTradeExecutor (单线程 + 64队列 + CallerRunsPolicy)
        ├─ openLong/Short(qty, onSuccess, onFailure)
        ├─ placeGridLimitOrder(price, size, onSuccess, onFailure) → 限价GTC单
        ├─ cancelOrder(orderId) → 取消指定挂单
        └─ placeTakeProfit → 条件单（plan-close-*-position, REST）
```

@@ -138,10 +142,11 @@
     │                    下单异常               ├─ 每根K线: 更新 unrealizedPnl
     │                        │                 ├─ cumPnl ≥ overallTp → STOPPED
     │                        │                 ├─ cumPnl ≤ -maxLoss → STOPPED
     │                        │                 ├─ 保证金超限 → 跳过开仓，队列照常更新
     │                        │                 ├─ 网格触发 → 开仓+设止盈+队列转移（以对方队列首元素为种子）
     │                        │                 ├─ 多>空且价格夹在中间 → 额外反向开仓
     │                        │                 └─ 转移元素贴近持仓均价 → 跳过（过滤）
     │                        │                 ├─ 保证金超限 → 跳过下单，队列照常更新（止盈队列仍更新）
     │                        │                 ├─ 方向区分 → processShortGrid 或 processLongGrid（二者选一）
     │                        │                 ├─ 网格触发 → 匹配队列→更新队列→止盈队列新增元素→
     │                        │                 │   取消对方旧限价单→挂新多空限价单→额外反向开仓
     │                        │                 └─ 多>空且价格夹在中间 → 额外反向开仓
     ▼                        ▼
   STOPPED  ←──────────────────┘
```
@@ -159,7 +164,7 @@

### 概述

策略采用"基底 + 价格网格队列"模式：先开一对基底多空仓位，然后以基底入场价为基准生成价格队列。每当K线穿破队列元素，就开新仓位并设止盈条件单，同时以对方队列首元素为种子生成新元素加入对方队列。
策略采用"基底 + 价格网格队列"模式：先开一对基底多空仓位，然后以基底入场价为基准生成价格队列和止盈队列。每当K线穿破队列元素，匹配后更新队列、补充止盈队列、挂限价单。仓位推送时从止盈队列消费止盈价并挂止盈条件单。

### 基底开仓

@@ -167,8 +172,26 @@
K线到达 → 双开基底（市价开多 + 市价开空）
  → 成交回调: baseLongOpened=true, longActive=true
  → 成交回调: baseShortOpened=true, shortActive=true
  → 两者都成交 → generateShortQueue() + generateLongQueue() → state=ACTIVE
  → 两者都成交 → generateShortQueue() + generateLongQueue() + 止盈队列初始化 + 限价单挂单 → state=ACTIVE
```

### 止盈队列初始化

基底队列生成后，两个止盈队列各填入一个元素：

| 止盈队列 | 初始元素 | 排序 |
|---------|---------|------|
| 多仓止盈队列 longTakeProfitQueue | longPriceQueue[0] + step | 升序（小→大） |
| 空仓止盈队列 shortTakeProfitQueue | shortPriceQueue[0] - step | 降序（大→小） |

### 初始限价单挂单

队列生成后立即用队列首元素挂两个 GTC 限价单：

| 方向 | 价格 | 数量 |
|------|------|------|
| 多仓限价单 | longPriceQueue[0] | +quantity |
| 空仓限价单 | shortPriceQueue[0] | −quantity |

### 网格队列生成

@@ -186,36 +209,42 @@
```
K线到达(ACTIVE状态):
│
├─ processShortGrid: 当前价 < 空仓队列元素（价格跌破了队列中的高价）
│   ├─ 匹配: 收集所有 > 当前价的空仓队列元素（降序，一旦遇≤即停止）
│   ├─ 空仓队列: 移除 matched，尾部补充新元素（尾价 − step 循环递减）
│   ├─ 多仓队列转移:
│   │   ├─ 以多仓队列首元素（最小价）为种子
│   │   ├─ 生成 matched.size() 个递减元素: seed − step × i
│   │   ├─ 贴近过滤: |currentPrice − longEntryPrice| < longEntryPrice × gridRate → 跳过
│   │   └─ 升序排列，截断到 gridQueueSize
│   └─ 下单（队列已更新，避免竞态）:
│       ├─ 保证金检查: positionInitialMargin / initialPrincipal < marginRatioLimit(20%)
│       │   ├─ 安全 → openShort 开空单
│       │   │   └─ 额外条件: 多>空 且 空仓均价 < 当前价 < 多仓均价×(1−gridRate) → openLong 额外开多一次
│       │   └─ 超限 → 跳过开仓
├─ closePrice > longPriceQueue[0] → processLongGrid（价格涨超队列首=最小价）
│   ├─ 匹配: 收集所有 < closePrice 的多仓队列元素（升序，一旦遇≥即停止）
│   ├─ 多仓队列: 移除 matched，尾部补充（尾价 + step 循环递增）
│   ├─ 空仓队列转移:
│   │   ├─ 以空仓队列首元素（最高价）为种子
│   │   ├─ 生成 matched.size() 个递增元素: seed + step × i
│   │   └─ 降序排列，截断到 gridQueueSize
│   ├─ 止盈队列: longTakeProfitQueue.add(新 longPriceQueue[0] + step) → 升序排列
│   ├─ 下单（队列已更新，避免竞态）:
│   │   ├─ 保证金检查: positionInitialMargin / initialPrincipal < marginRatioLimit(20%)
│   │   │   ├─ 安全 → 取消旧空仓限价单(cancelOrder) → 挂新多仓限价单 + 空仓限价单
│   │   │   └─ 超限 → 跳过下单
│   └─ 额外反向: closePrice 在多/空均价之间 → openShort
│
└─ processLongGrid: 当前价 > 多仓队列元素（价格涨超了队列中的低价）
    ├─ 匹配: 收集所有 < 当前价的多仓队列元素（升序，一旦遇≥即停止）
    ├─ 多仓队列: 移除 matched，尾部补充新元素（尾价 + step 循环递增）
    ├─ 空仓队列转移:
    │   ├─ 以空仓队列首元素（最高价）为种子
    │   ├─ 生成 matched.size() 个递增元素: seed + step × i
    │   ├─ 贴近过滤: |currentPrice − shortEntryPrice| < shortEntryPrice × gridRate → 跳过
    │   └─ 降序排列，截断到 gridQueueSize
    └─ 下单（队列已更新，避免竞态）:
        ├─ 保证金检查: 同上
        │   ├─ 安全 → openLong 开多单
        │   │   └─ 额外条件: 多>空 且 空仓均价×(1+gridRate) < 当前价 < 多仓均价 → openShort 额外开空一次
        │   └─ 超限 → 跳过开仓
└─ closePrice < shortPriceQueue[0] → processShortGrid（价格跌穿队列首=最高价）
    ├─ 匹配: 收集所有 > closePrice 的空仓队列元素（降序，一旦遇≤即停止）
    ├─ 空仓队列: 移除 matched，尾部补充（尾价 − step 循环递减）
    ├─ 多仓队列转移:
    │   ├─ 以多仓队列首元素（最小价）为种子
    │   ├─ 生成 matched.size() 个递减元素: seed − step × i
    │   └─ 升序排列，截断到 gridQueueSize
    ├─ 止盈队列: shortTakeProfitQueue.add(新 shortPriceQueue[0] − step) → 降序排列
    ├─ 下单（队列已更新，避免竞态）:
    │   ├─ 保证金检查: 同上
    │   │   ├─ 安全 → 取消旧多仓限价单(cancelOrder) → 挂新空仓限价单 + 多仓限价单
    │   │   └─ 超限 → 跳过下单
    └─ 额外反向: closePrice 在多/空均价之间 → openLong

closePrice 既不 > longPriceQueue[0] 也不 < shortPriceQueue[0] → 跳过本次K线
```

### 队列转移规则（新）
> **一个K线只触发一个方向。** 例如 closePrice=2295 时 longPriceQueue[0]=2277.9<2295 → 仅触发 processLongGrid。
> **只取消对方旧单。** 触发方向对应的旧限价单大概率已成交，只取消对方未成交的旧限价单。
> **限价单为 GTC**，挂新单前先取消旧单解决堆积问题。

### 队列转移规则

触发后**不再简单复制** matched 元素到对方队列，而是以对方队列首元素为种子，按绝对步长 step 生成新元素：

@@ -224,32 +253,16 @@
| 空仓触发 → | 多仓队列 | 多仓队列首元素（最小价） | 种子 − step × i | 升序 |
| 多仓触发 → | 空仓队列 | 空仓队列首元素（最高价） | 种子 + step × i | 降序 |

### 贴近持仓均价过滤（新）

转移生成新元素时，若元素与对应方向持仓均价的差距小于 gridRate，则跳过：

| 目标队列 | 过滤条件 | 含义 |
|---------|---------|------|
| 多仓队列 | \|elem − longEntryPrice\| < longEntryPrice × gridRate | 太贴近多仓成本，跳过 |
| 空仓队列 | \|elem − shortEntryPrice\| < shortEntryPrice × gridRate | 太贴近空仓成本，跳过 |

> 过滤仅在对应方向有持仓时生效（entryPrice > 0），避免在持仓成本附近生成无效网格线。

### 额外反向开仓条件（新）
### 额外反向开仓条件

当触发价夹在多/空持仓均价之间，且多仓均价大于空仓均价（多>空倒挂）时，额外反向开仓一次：

| 触发方向 | 额外操作 | 条件 |
|---------|---------|------|
| 空仓队列触发 | 额外开多 | shortEntryPrice > 0 && longEntryPrice > shortEntryPrice && shortEntryPrice < currentPrice < longEntryPrice × (1 − gridRate) |
| 多仓队列触发 | 额外开空 | shortEntryPrice > 0 && longEntryPrice > shortEntryPrice && shortEntryPrice × (1 + gridRate) < currentPrice < longEntryPrice |
| 空仓队列触发 | 额外开多 | shortEntryPrice > 0 && longEntryPrice > shortEntryPrice && shortEntryPrice < currentPrice < longEntryPrice |
| 多仓队列触发 | 额外开空 | shortEntryPrice > 0 && longEntryPrice > shortEntryPrice && shortEntryPrice < currentPrice < longEntryPrice |

**条件解释：**
- `longEntryPrice > shortEntryPrice`：多仓均价高于空仓均价（"倒挂"状态）
- `shortEntryPrice × (1 + gridRate) < currentPrice`：空仓触发时金额够远离空仓均价
- `currentPrice < longEntryPrice × (1 − gridRate)`：空仓触发时金额够远离多仓均价

> 背后的思路：当"多亏空赚"发生倒挂时，在价格区间中间补一单反方向仓位，利用均值回归获利。
> 条件统一简化：两个方向共用同一条件 `shortEntryPrice < currentPrice < longEntryPrice`，即当前价夹在多仓均价和空仓均价之间。

### 队列转移示意

@@ -259,6 +272,8 @@
初始状态:
  空仓队列: [2262.1, 2254.2, 2246.3, 2238.4]  (降序, shortBaseEntryPrice−step 起递减)
  多仓队列: [2277.9, 2285.8, 2293.7, 2301.6]  (升序, shortBaseEntryPrice+step 起递增)
  多止盈队列: [2285.8]  (longPriceQueue[0]+step)
  空止盈队列: [2254.2]  (shortPriceQueue[0]−step)

价格涨到 2290 → processLongGrid 触发:
  匹配: [2277.9, 2285.8]（都 < 2290）
@@ -270,12 +285,17 @@
  空仓队列转移:
    种子=空仓首元素 2262.1
    生成: 2262.1+7.9=2270.0, 2262.1+7.9×2=2277.9
    贴近过滤(shortEntryPrice=2270):
      |2270.0−2270|=0.0 < 2270×0.0035=7.9 → 跳过
      |2277.9−2270|=7.9 ≥ 7.9 → 通过
    空仓队列: [2277.9, 2262.1, 2254.2, 2246.3, 2238.4] → 截断到4 → [2262.1, 2254.2, 2246.3, 2238.4]（2277.9被移除...）
    空仓队列: [2262.1, 2270.0, 2277.9, 2254.2, 2246.3, 2238.4] → 截断到4 → [2277.9, 2270.0, 2262.1, 2254.2]

  注：当空仓队列已满时，新元素可能因排序+截断被丢弃。缩小 gridRate 可增加步长密度。
  止盈队列: longTakeProfitQueue.add(2293.7+7.9) = 2301.6
    → [2285.8, 2301.6]  (升序)

  挂单: 取消旧空仓限价单 → 挂新多单(2293.7) + 新空单(2277.9)

仓位推送（多单 2277.9 成交）:
  long size: 1→2，增量1
  消费止盈队列: longTakeProfitQueue.remove(0) = 2285.8
  挂止盈单: tp=2285.8, size=1, plan-close-long-position
```

---
@@ -302,39 +322,46 @@
  → gridTradeService.startGrid() → state=WAITING_KLINE
```

### 阶段 2：首次开仓 → 生成网格队列
### 阶段 2：基底开仓 → 生成网格队列 → 挂限价单

```
K线推送 → onKline(closePrice) → state=OPENING
  → executor.openLong(qty, onSuccess, onFailure)
    → 成交 → 仓位推送: DUAL_LONG, size>0, entryPrice=X
      → baseLongOpened=true, longBaseEntryPrice=X
      → tryGenerateQueues(): 双基底都成交? → 生成队列 → state=ACTIVE
      → tryGenerateQueues(): 双基底都成交? → 生成队列+止盈队列+挂限价单 → state=ACTIVE
  → executor.openShort(-qty, onSuccess, onFailure)
    → 成交 → 仓位推送: DUAL_SHORT, size<0, entryPrice=Y
      → baseShortOpened=true, shortBaseEntryPrice=Y
      → tryGenerateQueues(): 双基底都成交? → 生成队列 → state=ACTIVE
      → tryGenerateQueues(): 双基底都成交? → 生成队列+止盈队列+挂限价单 → state=ACTIVE
```

### 阶段 3：ACTIVE 状态 — K线驱动网格
### 阶段 3：ACTIVE 状态 — K线驱动网格 + 止盈队列消费

```
每根K线 → onKline → updateUnrealizedPnl → processShortGrid + processLongGrid
每根K线 → onKline → updateUnrealizedPnl → 方向区分（一个K线只触发一个方向）

仓位推送（每次开仓成交后自动触发）:
  → DUAL_LONG, size>0, 非基底 → 设多头止盈单：止盈价=longPriceQueue[0]（多仓队列首元素），
      使用 plan-close-long-position，平仓张数=-quantity（负=平多），rule=NUMBER_1(≥)
  → DUAL_SHORT, size<0, 非基底 → 设空头止盈单：止盈价=shortPriceQueue[0]（空仓队列首元素），
      使用 plan-close-short-position，平仓张数=+quantity（正=平空），rule=NUMBER_2(≤)
  → DUAL_LONG, size>0, 非基底:
      按 quantity 为单位计算仓位增量(newUnits)，逐个消费止盈队列:
        for each newUnit:
          tpPrice = longTakeProfitQueue.remove(0) 或 (止盈队列为空时) longEntryPrice + step 兜底
          executor.placeTakeProfit(tpPrice, NUMBER_1, plan-close-long-position, -quantity)
  → DUAL_SHORT, size<0, 非基底:
      同上方式消费空仓止盈队列:
        for each newUnit:
          tpPrice = shortTakeProfitQueue.remove(0) 或 shortEntryPrice - step 兜底
          executor.placeTakeProfit(tpPrice, NUMBER_2, plan-close-short-position, quantity)

K线触发网格后:
  → processLongGrid: 限价多单成交后，仓位推送触发止盈队列消费
  → processShortGrid: 限价空单成交后，仓位推送触发止盈队列消费

额外反向开仓（多>空倒挂时）:
  → 空仓队列触发 + 条件满足 → 额外开多一次
  → 多仓队列触发 + 条件满足 → 额外开空一次
  → 统一条件: shortEntryPrice < currentPrice < longEntryPrice
  → 空仓触发 → 额外开多(openLong)
  → 多仓触发 → 额外开空(openShort)
```

> 止盈由 Gate 服务端条件单自动执行。服务端监控价格，达到触发价后自动平仓。
> 每次网格触发开仓 quantity 张，只在该批张数上设止盈，与之前已设的止盈单互不影响。
> 平仓后仓位减少 quantity 张，盈亏通过 position_closes 频道推送到 cumulativePnl。

### 阶段 4：停止