From 4cb8c93cf1784a8e33458000156e6db22271b500 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Thu, 14 May 2026 15:40:21 +0800
Subject: [PATCH] refactor(gateApi): 重构网格交易策略核心逻辑
---
src/main/java/com/xcong/excoin/modules/gateApi/GateGridTradeService.java | 87 ++++---
src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md | 470 +++++++++++++++++++++-------------------------
2 files changed, 265 insertions(+), 292 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/GateGridTradeService.java b/src/main/java/com/xcong/excoin/modules/gateApi/GateGridTradeService.java
index 00b09c6..409f59c 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/GateGridTradeService.java
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/GateGridTradeService.java
@@ -54,10 +54,10 @@
* ├─ 每根K线 → 更新 unrealizedPnl → 方向判断
* │ ├─ closePrice > longPriceQueue[0] → processLongGrid
* │ └─ closePrice < shortPriceQueue[0] → processShortGrid
- * ├─ processShortGrid: 匹配空仓队列 → 队列转移→ 挂新空仓+多仓条件单
- * ├─ processLongGrid: 匹配多仓队列 → 队列转移→ 挂新多仓+空仓条件单
- * ├─ 订单推送(新) → onOrderUpdate → Map 匹配止盈价 → 挂止盈条件单
- * ├─ 仓位推送 → 更新均价/持仓量、处理反向单
+ * ├─ processShortGrid: 匹配空仓队列 → 本队补充 → 挂空仓+多仓条件单（止盈价存入Map）
+ * ├─ processLongGrid: 匹配多仓队列 → 本队补充 → 挂多仓+空仓条件单（止盈价存入Map）
+ * ├─ 订单推送(futures.orders) → onOrderUpdate → Map 匹配止盈价 → 挂止盈条件单
+ * ├─ 仓位推送 → 更新均价/持仓量、仓位减少时处理反向单
* ├─ 平仓推送 → 累加 cumulativePnl
* ├─ 保证金安全阀 → 超限跳过挂单，队列照常更新
* └─ cumulativePnl ≥ overallTp 或 ≤ -maxLoss → STOPPED
@@ -138,7 +138,7 @@
/** 基底空头入场价 */
private BigDecimal shortBaseEntryPrice;
- /** 基底多头入场价 */
+ /** 基底多头入场价（仅记录，当前未被业务逻辑消费，保留以备后续使用） */
private BigDecimal longBaseEntryPrice;
/** 基底多头是否已开 */
private volatile boolean baseLongOpened = false;
@@ -389,11 +389,14 @@
* <li><b>有仓位 (size ≠ 0)</b>：
* <ul>
* <li>首次开仓（基底）：标记 baseOpened=true，记录基底入场价，双基底都成交后生成网格队列</li>
- * <li>仓位净增加（size > 之前记录值）：说明网格触发了新开仓 → 取对应方向队列首元素为止盈价，设止盈条件单</li>
- * <li>仓位减少或不变（止盈平仓后）：仅更新 positionSize，不重复设止盈</li>
+ * <li>仓位净减少（size.abs() < 之前记录值）：止盈平仓后 → 检查反向条件单条件 →
+ * 满足时以 entryPrice ± step 为止盈价挂反向市价单（订单ID + 止盈价存入 Map）</li>
+ * <li>仓位净增加或不变：仅更新 positionSize，止盈由 {@link #onOrderUpdate} 通过订单订阅匹配处理</li>
* </ul>
* </li>
* <li><b>无仓位 (size = 0)</b>：清空活跃标记和持仓量</li>
+ * <li><b>Map 截断</b>：currentLongOrderIds / currentShortOrderIds 超过 5 个时，
+ * 从 LinkedHashMap 头部删除最旧条目，保留最新 5 个</li>
* </ul>
*
* @param contract 合约名称
@@ -554,12 +557,13 @@
* 尝试生成网格队列。双基底（多+空）都成交后才触发：
* <ol>
* <li>生成空仓价格队列（降序）和多仓价格队列（升序）</li>
- * <li>初始化止盈队列：多仓首元素 + step、空仓首元素 − step</li>
- * <li>挂初始多仓条件单（触发价 = 多仓队列首元素，rule=NUMBER_1 ≥触发价时开多）</li>
- * <li>挂初始空仓条件单（触发价 = 空仓队列首元素，rule=NUMBER_2 ≤触发价时开空）</li>
- * <li>条件单 ID 存入对应 currentXxxOrderIds 集合</li>
+ * <li>挂初始多仓条件单（触发价 = 多仓队列首元素，rule=NUMBER_1 ≥触发价时开多），
+ * 止盈价 = 触发价 + step，通过 onSuccess 回调将 orderId → 止盈价存入 currentLongOrderIds</li>
+ * <li>挂初始空仓条件单（触发价 = 空仓队列首元素，rule=NUMBER_2 ≤触发价时开空），
+ * 止盈价 = 触发价 − step，通过 onSuccess 回调将 orderId → 止盈价存入 currentShortOrderIds</li>
* <li>状态切换为 ACTIVE</li>
* </ol>
+ * 条件单成交后由 {@link #onOrderUpdate} 匹配止盈价并挂止盈条件单。
*/
private void tryGenerateQueues() {
if (baseLongOpened && baseShortOpened) {
@@ -638,20 +642,17 @@
* <h3>执行流程</h3>
* <ol>
* <li>匹配队列元素 → 为空则直接返回，不触发</li>
- * <li>空仓队列：移除 matched 元素，从尾部最小值递减 step 补充等量新元素，重新降序排序</li>
- * <li>多仓队列：以多仓首元素（最小价）为基准递减 step，生成 matched.size() 个新元素加入，
- * 升序排序，超限截尾</li>
- * <li>空仓止盈队列：始终加入新空仓首元素 − step（降序排序），不受守卫限制</li>
- * <li>保证金检查 → 不安全则跳过挂单（队列和止盈队列照常更新），安全则继续</li>
- * <li>挂新空仓条件单（触发价 = 新空仓首元素，rule=NUMBER_2 ≤触发价时开空，size=负）</li>
- * <li>多仓条件单守卫：newLongFirst < longEntryPrice 时才执行
- * → 取消所有旧多仓条件单（currentLongOrderIds） → 清空集合 →
- * 多仓止盈队列加入 newLongFirst + step →
- * 挂新多仓条件单（触发价 = newLongFirst，rule=NUMBER_1 ≥触发价时开多，size=正）；
- * 不满足时保持旧多仓条件单不变，也不更新多仓止盈队列</li>
- * <li>反向开多判断：newShortFirst > shortEntryPrice 且 < longEntryPrice 且 longPositionSize < 3
- * → 挂反向条件多单（触发价 = newShortFirst），止盈价 = newShortFirst + step 加入多仓止盈队列</li>
+ * <li>空仓队列：移除 matched 元素，从尾部递减 step 补充等量新元素，重新降序排序</li>
+ * <li>多仓队列：<b>不再更新</b>（队列转移逻辑已移除）</li>
+ * <li>保证金检查 → 不安全则跳过挂单（队列照常更新），安全则继续</li>
+ * <li>挂新空仓条件单（触发价 = newShortFirst，rule=NUMBER_2，止盈 = newShortFirst − step，
+ * orderId → 止盈价存入 currentShortOrderIds）</li>
+ * <li>多仓条件单守卫：newLongFirst = newShortFirst + step × 2，
+ * 若 newLongFirst < longEntryPrice → 挂多仓条件单（止盈 = newLongFirst + step，
+ * orderId → 止盈价存入 currentLongOrderIds）</li>
* </ol>
+ * 条件单成交后由 {@link #onOrderUpdate} 匹配止盈价并挂止盈条件单。
+ * 反向条件单不再在此处理，改为在 {@link #onPositionUpdate} 仓位净减少时触发。
*
* @param currentPrice 当前 K 线收盘价（最新成交价）
*/
@@ -681,6 +682,19 @@
}
shortPriceQueue.sort((a, b) -> b.compareTo(a));
}
+
+// synchronized (longPriceQueue) {
+// BigDecimal first = longPriceQueue.isEmpty() ? matched.get(matched.size() - 1) : longPriceQueue.get(0);
+// BigDecimal gridStep = config.getStep();
+// for (int i = 1; i <= matched.size(); i++) {
+// BigDecimal elem = first.subtract(gridStep.multiply(BigDecimal.valueOf(i))).setScale(1, RoundingMode.HALF_UP);
+// longPriceQueue.add(elem);
+// }
+// longPriceQueue.sort(BigDecimal::compareTo);
+// while (longPriceQueue.size() > config.getGridQueueSize()) {
+// longPriceQueue.remove(longPriceQueue.size() - 1);
+// }
+// }
if (!isMarginSafe()) {
log.warn("[Gate] 保证金超限，跳过挂条件单");
@@ -718,20 +732,17 @@
* <h3>执行流程</h3>
* <ol>
* <li>匹配队列元素 → 为空则直接返回，不触发</li>
- * <li>多仓队列：移除 matched 元素，从尾部最大值递增 step 补充等量新元素，重新升序排序</li>
- * <li>空仓队列：以空仓首元素（最高价）为基准递增 step，生成 matched.size() 个新元素加入，
- * 降序排序，超限截尾</li>
- * <li>多仓止盈队列：始终加入新多仓首元素 + step（升序排序），不受守卫限制</li>
- * <li>保证金检查 → 不安全则跳过挂单（队列和止盈队列照常更新），安全则继续</li>
- * <li>挂新多仓条件单（触发价 = 新多仓首元素，rule=NUMBER_1 ≥触发价时开多，size=正）</li>
- * <li>空仓条件单守卫：newShortFirst > shortEntryPrice 时才执行
- * → 取消所有旧空仓条件单（currentShortOrderIds） → 清空集合 →
- * 空仓止盈队列加入 newShortFirst − step →
- * 挂新空仓条件单（触发价 = newShortFirst，rule=NUMBER_2 ≤触发价时开空，size=负）；
- * 不满足时保持旧空仓条件单不变，也不更新空仓止盈队列</li>
- * <li>反向开空判断：newLongFirst > shortEntryPrice 且 < longEntryPrice 且 shortPositionSize < 3
- * → 挂反向条件空单（触发价 = newLongFirst），止盈价 = newLongFirst − step 加入空仓止盈队列</li>
+ * <li>多仓队列：移除 matched 元素，从尾部递增 step 补充等量新元素，重新升序排序</li>
+ * <li>空仓队列：<b>不再更新</b>（队列转移逻辑已移除）</li>
+ * <li>保证金检查 → 不安全则跳过挂单（队列照常更新），安全则继续</li>
+ * <li>挂新多仓条件单（触发价 = newLongFirst，rule=NUMBER_1，止盈 = newLongFirst + step，
+ * orderId → 止盈价存入 currentLongOrderIds）</li>
+ * <li>空仓条件单守卫：newShortFirst = newLongFirst − step × 2，
+ * 若 newShortFirst > shortEntryPrice → 挂空仓条件单（止盈 = newShortFirst − step，
+ * orderId → 止盈价存入 currentShortOrderIds）</li>
* </ol>
+ * 条件单成交后由 {@link #onOrderUpdate} 匹配止盈价并挂止盈条件单。
+ * 反向条件单不再在此处理，改为在 {@link #onPositionUpdate} 仓位净减少时触发。
*
* @param currentPrice 当前 K 线收盘价（最新成交价）
*/
@@ -769,13 +780,11 @@
// for (int i = 1; i <= matched.size(); i++) {
// BigDecimal elem = first.add(gridStep.multiply(BigDecimal.valueOf(i))).setScale(1, RoundingMode.HALF_UP);
// shortPriceQueue.add(elem);
-// log.info("[Gate] 空队列增加:{}", elem);
// }
// shortPriceQueue.sort((a, b) -> b.compareTo(a));
// while (shortPriceQueue.size() > config.getGridQueueSize()) {
// shortPriceQueue.remove(shortPriceQueue.size() - 1);
// }
-// log.info("[Gate] 现空队列:{}", shortPriceQueue);
// }
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md b/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
index b7ae5c9..42a2dc6 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md
@@ -7,10 +7,8 @@
| [GateWebSocketClientManager](#gatewebsocketclientmanager) | `@Component` | Spring 启动入口，组装组件 + 生命周期 |
| [GateConfig](#gateconfig) | 配置 | Builder 模式：API 密钥、合约、策略参数、环境切换 |
| [GateKlineWebSocketClient](#gateklinewebsocketclient) | WS 连接管理 | 连接/心跳/重连/消息路由 |
-| [GateGridTradeService](#gategridtradeservice) | 交易服务 | 网格队列策略 + 条件开仓单 + 止盈队列 + 反向条件单 |
+| [GateGridTradeService](#gategridtradeservice) | 策略核心 | 网格队列 + 条件开仓单 + 订单订阅止盈 + 反向条件单 |
| [GateTradeExecutor](#gatetradeexecutor) | 异步执行器 | 独立线程池执行 REST 下单，成功/失败双回调 |
-| [GateWebSocketClientMain](#gatewebsocketclientmain) | main 入口 | 独立测试启动 |
-| [Example.java](#examplejava) | 示例 | Gate SDK 用法参考 |
### wsHandler 子包
@@ -19,8 +17,9 @@
| `wsHandler/GateChannelHandler.java` | **接口** | subscribe / unsubscribe / handleMessage / getChannelName |
| `wsHandler/AbstractPrivateChannelHandler.java` | **抽象类** | 私有频道基类：HMAC-SHA512 签名 + 认证请求 |
| `wsHandler/handler/CandlestickChannelHandler.java` | 公开频道 | K 线解析 → `onKline()` |
-| `wsHandler/handler/PositionsChannelHandler.java` | 私有频道 | 仓位推送 → `onPositionUpdate()`（传 `Position.ModeEnum`），日志输出全部20个推送字段 |
+| `wsHandler/handler/PositionsChannelHandler.java` | 私有频道 | 仓位推送 → `onPositionUpdate()`，日志输出全部 20 个推送字段 |
| `wsHandler/handler/PositionClosesChannelHandler.java` | 私有频道 | 平仓推送 → `onPositionClose()` |
+| `wsHandler/handler/OrdersChannelHandler.java` | 私有频道 | 订单推送 → `onOrderUpdate()`（订单订阅止盈匹配） |
---
@@ -40,9 +39,21 @@
│ │Candlestick H │ │
│ │Positions H │ │
│ │PosCloses H │ │
+│ │Orders H │ │
│ └──────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
+
+---
+
+## WebSocket 频道
+
+| 频道 | 类型 | 作用 |
+|------|------|------|
+| `futures.candlesticks` | 公开 | K 线推送 → `onKline()` 驱动网格触发 |
+| `futures.positions` | 私有 | 仓位推送 → `onPositionUpdate()` 记录入场价/持仓量、处理反向单 |
+| `futures.position_closes` | 私有 | 平仓推送 → `onPositionClose()` 累加已实现盈亏 |
+| `futures.orders` | 私有 | 订单推送 → `onOrderUpdate()` 订阅条件单成交，匹配止盈价 |
---
@@ -65,23 +76,29 @@
├─ futures.positions (私有, HMAC-SHA512)
│ └─ PositionsChannelHandler
│ ├─ 解析 mode → Position.ModeEnum（DUAL_LONG / DUAL_SHORT）
-│ ├─ 日志输出全部 20 个推送字段（contract/mode/size/entry_price/.../update_id）
+│ ├─ 日志输出全部 20 个推送字段
│ └─ gridTradeService.onPositionUpdate(contract, mode, size, entryPrice)
-│ ├─ 有仓位: 标记活跃，首次成交记录入场价
-│ │ ├─ 基底开仓 → 首次成交 → 记录基底入场价 → 双基底都成交后
-│ │ │ 生成网格队列 + 止盈队列初始化 + 挂初始条件开仓单 → state=ACTIVE
-│ │ └─ 非基底（仓位净增） → 按 quantity 为单位计算增量，
-│ │ 逐个从止盈队列消费止盈价（队列不足时 entryPrice ± step 兜底）
-│ └─ 无仓位(size=0): 标记不活跃
+│ ├─ 有仓位: 基底首次成交记录入场价 → tryGenerateQueues
+│ ├─ 仓位净减少（size < positionSize）→ 检查反向条件单条件 →
+│ │ 满足则开反向市价单（止盈价 = entryPrice ± step），orderId+止盈价存入 Map
+│ ├─ 仓位不变或增加 → 仅更新 positionSize
+│ └─ 无仓位(size=0): 清空活跃标记和持仓量
│
├─ futures.position_closes (私有, HMAC-SHA512)
│ └─ PositionClosesChannelHandler
│ └─ gridTradeService.onPositionClose(contract, side, pnl)
│ └─ cumulativePnl += pnl → checkStopConditions()
│
+├─ futures.orders (私有, HMAC-SHA512) ← 订单订阅止盈核心
+│ └─ OrdersChannelHandler
+│ └─ gridTradeService.onOrderUpdate(orderId, status, finishAs)
+│ └─ 条件单成交（status=finished, finish_as=filled）→
+│ 从 Map 中 remove(orderId) 取出止盈价 →
+│ executor.placeTakeProfit(止盈价, ...)
+│
└─ 所有下单操作
└─ GateTradeExecutor (单线程 + 64队列 + CallerRunsPolicy)
- ├─ openLong/openShort → 市价 IOC 开仓（基底双开 + 额外反向开仓）
+ ├─ openLong/openShort → 市价 IOC 开仓（基底双开 + 反向开仓）
├─ placeConditionalEntryOrder → 条件开仓单（网格触发，服务端监控价格触发后市价 IOC）
├─ cancelConditionalOrder → 取消指定条件单
├─ placeTakeProfit → 止盈条件单（plan-close-*-position）
@@ -89,52 +106,6 @@
├─ placeGridLimitOrder → 【遗留】限价 GTC 单（当前策略未使用）
└─ cancelOrder → 【遗留】取消限价单（当前策略未使用）
```
-
-### PositionsChannelHandler 完整推送字段（20个）
-
-| 字段 | 类型 | 描述 |
-|------|------|------|
-| contract | String | 合约名称 |
-| mode | String | 持仓模式：dual_long / dual_short |
-| size | String/Integer | 合约张数（正=多头，负=空头） |
-| entry_price | Float | 开仓均价 |
-| cross_leverage_limit | Float | 全仓模式下的杠杆倍数上限 |
-| history_pnl | Float | 已平仓的仓位总盈亏 |
-| history_point | Float | 已平仓的点卡总盈亏 |
-| last_close_pnl | Float | 最近一次平仓的盈亏 |
-| leverage | Integer | 杠杆倍数（0=全仓，正数=逐仓） |
-| leverage_max | Integer | 当前风险限额下允许的最大杠杆倍数 |
-| liq_price | Float | 爆仓价格 |
-| maintenance_rate | Float | 当前风险限额下维持保证金比例 |
-| margin | Float | 保证金 |
-| realised_pnl | Float | 已实现盈亏 |
-| realised_point | Float | 点卡已实现盈亏 |
-| risk_limit | Integer | 风险限额 |
-| time | Integer | 更新 unix 时间戳（秒） |
-| time_ms | Integer | 更新 unix 时间戳（毫秒） |
-| user | String | 用户 ID |
-| update_id | Integer | 消息序列号，每次推送 order 后自增1 |
-
-> 以上 20 个字段在 PositionsChannelHandler.handleMessage() 中通过 SLF4J 日志全部输出。
-> 回调给 GateGridTradeService.onPositionUpdate() 的仅有 mode、size、entryPrice 三个核心字段。
-
----
-
-## GateChannelHandler 接口体系
-
-```
-GateChannelHandler (接口)
- ├── CandlestickChannelHandler (公开频道)
- └── AbstractPrivateChannelHandler (私有频道基类: HMAC-SHA512)
- ├── PositionsChannelHandler (解析 mode → Position.ModeEnum，日志输出20个字段)
- └── PositionClosesChannelHandler
-```
-
-- **subscribe**: 发送订阅请求。私有Handler自动附加 auth 字段
-- **unsubscribe**: 发送取消订阅请求（私有频道也带签名认证）
-- **handleMessage**: 解析推送数据并回调GateGridTradeService，返回true表示已处理
-- 消息路由: update/all事件 → 遍历channelHandlers → handler内部二次匹配channel名 → 匹配成功回调并停止遍历
-- **PositionsChannelHandler 特殊处理**: 推送的 mode 字符串（"dual_long"）通过 `Position.ModeEnum.fromValue()` 转为枚举
---
@@ -146,12 +117,13 @@
│ 下单异常 ├─ 每根K线: 更新 unrealizedPnl
│ │ ├─ cumPnl ≥ overallTp → STOPPED
│ │ ├─ cumPnl ≤ -maxLoss → STOPPED
- │ │ ├─ 保证金超限 → 跳过挂单，队列照常更新（止盈队列仍更新）
+ │ │ ├─ 保证金超限 → 跳过挂单，队列照常更新
│ │ ├─ 方向区分 → processShortGrid 或 processLongGrid（二者选一）
- │ │ ├─ 网格触发 → 匹配队列→更新队列→止盈入队→
- │ │ │ 取消对方旧条件单→挂新多空条件单→反向条件单
- │ │ └─ 仓位推送(净增张数) → 从止盈队列消费止盈价 →
- │ │ 挂止盈条件单（plan-close-*-position）
+ │ │ ├─ 网格触发 → 匹配队列→本队补充→挂新条件单
+ │ │ │ （止盈价随 orderId 存入 Map）
+ │ │ ├─ 订单推送(futures.orders) → 订阅匹配止盈价 →
+ │ │ │ 挂止盈条件单（plan-close-*-position）
+ │ │ └─ 仓位推送(净减少) → 反向市价单
▼ ▼
STOPPED ←──────────────────┘
```
@@ -160,26 +132,40 @@
|------|------|
| `WAITING_KLINE` | 等待首次K线价格 |
| `OPENING` | 正在异步开基底多空仓位（已提交到GateTradeExecutor） |
-| `ACTIVE` | 网格队列激活，K线触发网格 → 挂条件单 → 条件单成交后止盈 |
+| `ACTIVE` | 网格队列激活，K线触发网格 → 挂条件单 → 订单订阅匹配止盈 |
| `STOPPED` | 停止（盈利达标 / 亏损超限） |
---
-## 策略核心：网格队列 + 条件单 + 止盈队列
+## 策略核心：网格队列 + 条件单 + 订单订阅止盈
### 概述
-策略采用"基底 + 价格网格队列"模式：先开一对基底多空仓位，然后以基底入场价为基准生成价格队列和止盈队列。每当K线穿破队列元素，匹配后更新队列、补充止盈队列、取消旧条件单并挂新条件单。仓位推送时从止盈队列消费止盈价并挂止盈条件单。
+策略采用"基底 + 价格网格队列"模式：先开一对基底多空仓位，然后以基底入场价为基准生成价格队列。每当 K 线穿破队列元素，匹配后更新队列并挂新条件单。条件单成交后通过 `futures.orders` 推送匹配止盈价并挂止盈条件单。
-### 条件单设计（核心）
+### 核心数据结构
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| shortPriceQueue | `List<BigDecimal>` 同步列表 | 空仓价格队列，降序（大→小），容量 gridQueueSize |
+| longPriceQueue | `List<BigDecimal>` 同步列表 | 多仓价格队列，升序（小→大），容量 gridQueueSize |
+| currentLongOrderIds | `Map<String, BigDecimal>` 同步 LinkedHashMap | **多仓条件单映射**：orderId → 止盈价，超 5 个时截断保留最新 |
+| currentShortOrderIds | `Map<String, BigDecimal>` 同步 LinkedHashMap | **空仓条件单映射**：orderId → 止盈价，超 5 个时截断保留最新 |
+| shortBaseEntryPrice | `BigDecimal` | 基底空头入场价（仅记录，用于队列生成基准） |
+| longBaseEntryPrice | `BigDecimal` | 基底多头入场价（仅记录，当前未被业务逻辑消费） |
+| shortEntryPrice | `BigDecimal` | 当前空仓加权均价（推送实时更新） |
+| longEntryPrice | `BigDecimal` | 当前多仓加权均价（推送实时更新） |
+| shortPositionSize | `BigDecimal` | 当前空仓持仓量（绝对值） |
+| longPositionSize | `BigDecimal` | 当前多仓持仓量 |
+| cumulativePnl | `BigDecimal` | 累计已实现盈亏（平仓推送驱动） |
+| unrealizedPnl | `BigDecimal` | 未实现盈亏（每根K线更新） |
+| initialPrincipal | `BigDecimal` | 初始本金（启动时账户总资产） |
+
+### 条件单设计
**为什么用条件单而不是限价单？**
-限价单 `price=X, tif=GTC` 在价格位于挂单价有利侧时**会立即成交**。例如：
-- 多仓队列元素都在市场价之上，挂限价多单会立刻以市价成交
-- 空仓队列元素都在市场价之下，挂限价空单会立刻以市价成交
-
-改用 Gate API `FuturesPriceTriggeredOrder`（价格触发条件单），由服务端监控价格，**只有当前价格抵达触发价时才执行**，避免提前成交。
+限价单 `price=X, tif=GTC` 在价格位于挂单价有利侧时**会立即成交**。改用 Gate API `FuturesPriceTriggeredOrder`（价格触发条件单），由服务端监控价格，**只有当前价格抵达触发价时才执行**，避免提前成交。
**条件单结构**：
```
@@ -189,7 +175,28 @@
└─ order_type: strategy_type=NUMBER_0(价格触发), price_type=NUMBER_0(最新价)
```
-**执行逻辑**：服务端监控 → 最新价达到触发价 → 以市价 IOC 开仓（price="0" + tif=IOC）。
+### 订单订阅止盈机制（核心）
+
+**这是当前版本的止盈流程，替代了旧版的止盈队列消费模式。**
+
+```
+挂条件开仓单时 → onSuccess 回调 → currentXxxOrderIds.put(orderId, 止盈价)
+ ↓
+条件单成交 → futures.orders 推送 → onOrderUpdate(orderId, "finished", "filled")
+ ↓
+ currentXxxOrderIds.remove(orderId) 取出止盈价
+ ↓
+ executor.placeTakeProfit(止盈价, 方向参数)
+```
+
+止盈价计算：
+- **网格触发**（`processShortGrid`/`processLongGrid`）：`newFirst ± step`
+- **初始条件单**（`tryGenerateQueues`）：`queue[0] ± step`
+- **反向市价单**（`onPositionUpdate`）：`entryPrice ± step`
+
+### Map 截断机制
+
+`currentLongOrderIds` / `currentShortOrderIds` 为 `LinkedHashMap`（保持插入顺序）。在 `onPositionUpdate` 中，当 Map size > 5 时，从头部（最旧条目）开始删除，只保留最新 5 条。防止条件单挂单失败导致 Map 无限膨胀。
### 基底开仓
@@ -198,164 +205,116 @@
→ 成交回调: baseLongOpened=true, longActive=true
→ 成交回调: baseShortOpened=true, shortActive=true
→ 两者都成交 → generateShortQueue() + generateLongQueue()
- + 止盈队列初始化 + 挂初始条件开仓单 → state=ACTIVE
+ + 挂初始条件开仓单 → state=ACTIVE
```
-
-### 止盈队列初始化
-
-基底队列生成后，两个止盈队列各填入一个元素：
-
-| 止盈队列 | 初始元素 | 排序 |
-|---------|---------|------|
-| 多仓止盈队列 longTakeProfitQueue | longPriceQueue[0] + step | 升序（小→大） |
-| 空仓止盈队列 shortTakeProfitQueue | shortPriceQueue[0] - step | 降序（大→小） |
### 初始条件开仓单
队列生成后立即用队列首元素挂两个价格触发条件单：
-| 方向 | 触发价 | rule | size | 说明 |
-|------|--------|------|------|------|
-| 多仓条件单 | longPriceQueue[0] | NUMBER_1 (≥触发价) | +quantity | 价格涨到触发价时开多 |
-| 空仓条件单 | shortPriceQueue[0] | NUMBER_2 (≤触发价) | -quantity | 价格跌到触发价时开空 |
+| 方向 | 触发价 | rule | size | 止盈价（存入Map） |
+|------|--------|------|------|-------------------|
+| 多仓条件单 | longPriceQueue[0] | NUMBER_1 (≥触发价) | +quantity | 触发价 + step |
+| 空仓条件单 | shortPriceQueue[0] | NUMBER_2 (≤触发价) | -quantity | 触发价 − step |
### 网格队列生成
-以空头基底入场价 `shortBaseEntryPrice` 为唯一基准，计算绝对步长 `step = shortBaseEntryPrice × gridRate`（保留1位小数），存入 config。
+以空头基底入场价 `shortBaseEntryPrice` 为唯一基准，计算绝对步长 `step = shortBaseEntryPrice × gridRate`（保留1位小数）。
-两个队列均从 `shortBaseEntryPrice` 出发，按 `step` 绝对偏移生成 N 个价格（N = gridQueueSize，默认50）：
+两个队列均从 `shortBaseEntryPrice` 出发，按 `step` 绝对偏移生成 N 个价格（N = gridQueueSize，默认 50）：
| 队列 | 计算方式 | 排序 |
|------|---------|------|
-| 空仓队列 shortPriceQueue | 首元素 = shortBaseEntryPrice − step，后续依次 −step (i=0..N-1) | 降序（大→小） |
-| 多仓队列 longPriceQueue | 首元素 = shortBaseEntryPrice + step，后续依次 +step (i=0..N-1) | 升序（小→大） |
+| 空仓队列 shortPriceQueue | 首元素 = shortBaseEntryPrice − step，后续依次 −step | 降序（大→小） |
+| 多仓队列 longPriceQueue | 首元素 = shortBaseEntryPrice + step，后续依次 +step | 升序（小→大） |
-### K线触发网格
+---
+
+## K线触发网格
```
K线到达(ACTIVE状态):
│
-├─ closePrice > longPriceQueue[0] → processLongGrid（价格涨超队列首=最小价）
+├─ closePrice > longPriceQueue[0] → processLongGrid（价格涨超队列首）
│ ├─ 匹配: 收集所有 < closePrice 的多仓队列元素（升序，一旦遇≥即停止）
│ ├─ 多仓队列: 移除 matched，尾部补充（尾价 + step 循环递增）
-│ ├─ 空仓队列转移:
-│ │ ├─ 以空仓队列首元素（最高价）为种子
-│ │ ├─ 生成 matched.size() 个递增元素: seed + step × i
-│ │ └─ 降序排列，截断到 gridQueueSize
-│ ├─ 止盈队列: longTakeProfitQueue.add(新 longPriceQueue[0] + step) → 升序排列
-│ ├─ 下单（队列已更新，避免竞态）:
-│ │ ├─ 保证金检查: positionInitialMargin / initialPrincipal < marginRatioLimit(20%)
-│ │ │ ├─ 安全 →
-│ │ │ │ ├─ 挂新多仓条件单（触发价=新 long[0], rule=NUMBER_1, size=+qty）
-│ │ │ │ └─ 空仓条件单守卫: 新 short[0] > shortEntryPrice 时才执行
-│ │ │ │ ├─ 取消所有旧空仓条件单（currentShortOrderIds 遍历取消，清空集合）
-│ │ │ │ ├─ shortTakeProfitQueue.add(新 short[0] − step)
-│ │ │ │ └─ 挂新空仓条件单（触发价=新 short[0], rule=NUMBER_2, size=-qty）
-│ │ │ │ └─ 不满足 → 旧空仓条件单+空仓止盈队列保持不动
-│ │ │ └─ 超限 → 跳过挂单（队列和止盈队列照常更新）
-│ └─ 反向条件单:
-│ ├─ 条件: 新 long[0] > shortEntryPrice && 新 long[0] < longEntryPrice && shortPositionSize < 3
-│ ├─ 满足 → 挂反向条件空单（触发价=新 long[0], rule=NUMBER_2, size=-qty）
-│ └─ 同时: shortTakeProfitQueue.add(触发价 - step)
+│ ├─ 空仓队列: 不再更新（队列转移逻辑已移除）
+│ ├─ 保证金检查:
+│ │ ├─ 安全 → 挂新多仓条件单（触发价=新 long[0], 止盈=新 long[0]+step, orderId→Map）
+│ │ │ → 空仓守卫: newShortFirst = newLongFirst − step×2,
+│ │ │ 若 > shortEntryPrice → 挂新空仓条件单（止盈=新short[0]−step, orderId→Map）
+│ │ └─ 超限 → 跳过挂单（队列照常更新）
+│ └─ 条件单成交后由 futures.orders 推送 → onOrderUpdate 匹配止盈价 → 挂止盈条件单
│
-└─ closePrice < shortPriceQueue[0] → processShortGrid（价格跌穿队列首=最高价）
+└─ closePrice < shortPriceQueue[0] → processShortGrid（价格跌穿队列首）
├─ 匹配: 收集所有 > closePrice 的空仓队列元素（降序，一旦遇≤即停止）
├─ 空仓队列: 移除 matched，尾部补充（尾价 − step 循环递减）
- ├─ 多仓队列转移:
- │ ├─ 以多仓队列首元素（最小价）为种子
- │ ├─ 生成 matched.size() 个递减元素: seed − step × i
- │ └─ 升序排列，截断到 gridQueueSize
- ├─ 止盈队列: shortTakeProfitQueue.add(新 shortPriceQueue[0] − step) → 降序排列
- ├─ 下单（队列已更新，避免竞态）:
- │ ├─ 保证金检查: 同上
- │ │ ├─ 安全 →
- │ │ │ ├─ 挂新空仓条件单（触发价=新 short[0], rule=NUMBER_2, size=-qty）
- │ │ │ └─ 多仓条件单守卫: 新 long[0] < longEntryPrice 时才执行
- │ │ │ ├─ 取消所有旧多仓条件单（currentLongOrderIds 遍历取消，清空集合）
- │ │ │ ├─ longTakeProfitQueue.add(新 long[0] + step)
- │ │ │ └─ 挂新多仓条件单（触发价=新 long[0], rule=NUMBER_1, size=+qty）
- │ │ │ └─ 不满足 → 旧多仓条件单+多仓止盈队列保持不动
- │ │ └─ 超限 → 跳过挂单（队列和止盈队列照常更新）
- └─ 反向条件单:
- ├─ 条件: 新 short[0] > shortEntryPrice && 新 short[0] < longEntryPrice && longPositionSize < 3
- ├─ 满足 → 挂反向条件多单（触发价=新 short[0], rule=NUMBER_1, size=+qty）
- └─ 同时: longTakeProfitQueue.add(触发价 + step)
+ ├─ 多仓队列: 不再更新（队列转移逻辑已移除）
+ ├─ 保证金检查:
+ │ ├─ 安全 → 挂新空仓条件单（触发价=新 short[0], 止盈=新short[0]−step, orderId→Map）
+ │ │ → 多仓守卫: newLongFirst = newShortFirst + step×2,
+ │ │ 若 < longEntryPrice → 挂新多仓条件单（止盈=新long[0]+step, orderId→Map）
+ │ └─ 超限 → 跳过挂单（队列照常更新）
+ └─ 条件单成交后由 futures.orders 推送 → onOrderUpdate 匹配止盈价 → 挂止盈条件单
closePrice 既不 > longPriceQueue[0] 也不 < shortPriceQueue[0] → 跳过本次K线
```
-> **一个K线只触发一个方向。** 例如 closePrice=2295 时 longPriceQueue[0]=2277.9<2295 → 仅触发 processLongGrid。
-> **只取消对方旧条件单。** 触发方向对应的旧条件单大概率已成交，只取消对方未成交的旧条件单。
-> **条件单 ID 用 List<String> 管理。** 由于反向条件单也需要被追踪和取消，用同步列表统一管理（`Collections.synchronizedList`）。
+> **关键变更**：不再有"队列转移"（对方队列不再更新）、不再有"取消旧条件单"（旧单由 Map 自动覆盖或服务端自动取消）、不再有"止盈队列"（改为订单订阅匹配）。
+> 反向条件单不再在 process*Grid 中处理，改为在 onPositionUpdate 仓位净减少时触发。
-### 队列转移规则
-
-触发后**不再简单复制** matched 元素到对方队列，而是以对方队列首元素为种子，按绝对步长 step 生成新元素：
-
-| 触发方向 | 目标队列 | 种子元素 | 生成公式 | 排序 |
-|---------|---------|---------|---------|------|
-| 空仓触发 → | 多仓队列 | 多仓队列首元素（最小价） | 种子 − step × i | 升序 |
-| 多仓触发 → | 空仓队列 | 空仓队列首元素（最高价） | 种子 + step × i | 降序 |
-
-### 反向条件单条件
-
-当新网格首元素价格夹在多/空持仓均价之间，且反向持仓张数不超过3张时，额外挂一张反向条件单：
-
-```
-newFirstPrice > shortEntryPrice // 价格在空仓均价之上
-AND newFirstPrice < longEntryPrice // 价格在多仓均价之下
-AND 反向持仓张数 < 3 // 最多同时持有3张反向仓位
-```
-
-满足条件时以 newFirstPrice 为触发价挂反向条件单，同时将 newFirstPrice ± step 加入对方止盈队列。
-
-### 条件单 ID 管理
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| currentLongOrderIds | `List<String>` | 多仓条件单 ID 集合，同步列表 |
-| currentShortOrderIds | `List<String>` | 空仓条件单 ID 集合，同步列表 |
-
-每次网格触发时：
-1. 遍历对方方向的 `currentXxxOrderIds`，逐个调用 `cancelConditionalOrder` 取消
-2. 清空集合
-3. 挂新条件单，将新 ID 加入对应集合
-4. 如有反向条件单，其 ID 也加入对应方向集合
-
-### 队列转移示意
+### 队列更新示意
```
ETH_USDT, gridRate=0.0035, shortBaseEntryPrice=2270, step=2270×0.0035≈7.9, gridQueueSize=4:
初始状态:
- 空仓队列: [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)
- 初始条件单: 多仓触发价=2277.9, 空仓触发价=2262.1
+ 空仓队列: [2262.1, 2254.2, 2246.3, 2238.4] (降序)
+ 多仓队列: [2277.9, 2285.8, 2293.7, 2301.6] (升序)
+ 初始条件单: 多仓触发价=2277.9(止盈=2285.8→currentLongOrderIds),
+ 空仓触发价=2262.1(止盈=2254.2→currentShortOrderIds)
价格涨到 2290 → processLongGrid 触发:
匹配: [2277.9, 2285.8]（都 < 2290）
多仓队列: 移除[2277.9,2285.8] → [2293.7,2301.6]
- 补充: max=2301.6 → 2301.6+7.9=2309.5 → 2309.5+7.9=2317.4
+ 补充: 2301.6+7.9=2309.5 → 2309.5+7.9=2317.4
→ [2293.7, 2301.6, 2309.5, 2317.4]
- 空仓队列转移:
- 种子=空仓首元素 2262.1
- 生成: 2262.1+7.9=2270.0, 2262.1+7.9×2=2277.9
- 空仓队列: [2262.1, 2270.0, 2277.9, 2254.2, 2246.3, 2238.4] → 截断到4 → [2277.9, 2270.0, 2262.1, 2254.2]
+ 空仓队列: 不变（队列转移已移除）→ [2262.1, 2254.2, 2246.3, 2238.4]
- 止盈队列: longTakeProfitQueue.add(2293.7+7.9) = 2301.6
- → [2285.8, 2301.6] (升序)
+ 挂新多仓条件单(触发价=2293.7, 止盈=2301.6→currentLongOrderIds)
+ 空仓守卫: newShortFirst=2293.7−15.8=2277.9 > 2262.1? → 满足，
+ 挂新空仓条件单(触发价=2277.9, 止盈=2270.0→currentShortOrderIds)
- 取消旧空仓条件单（currentShortOrderIds） → 挂新多仓条件单(触发价=2293.7) + 新空仓条件单(触发价=2277.9)
+条件单 2293.7 成交 → futures.orders 推送:
+ → onOrderUpdate(orderId, "finished", "filled")
+ → currentLongOrderIds.remove(orderId) = 2301.6
+ → placeTakeProfit(2301.6, NUMBER_1, plan-close-long-position, -1)
+```
-仓位推送（多单 2277.9 成交 → 条件单触发开仓）:
- long size: 1→2，增量1
- 消费止盈队列: longTakeProfitQueue.remove(0) = 2285.8
- 挂止盈单: triggerPrice=2285.8, rule=NUMBER_1, order_type=plan-close-long-position, size=-1
- 止盈单执行: price="0", tif=IOC (触发后市价平仓)
+---
+
+## 仓位更新逻辑（onPositionUpdate）
+
+```
+仓位推送:
+├─ size ≠ 0:
+│ ├─ 基底首次成交 → 记录 baseEntryPrice → tryGenerateQueues
+│ ├─ 仓位净减少（size.abs() < positionSize）:
+│ │ ├─ DUAL_LONG 仓位减少且有反向条件单（newShortFirst > shortEntryPrice
+│ │ │ 且 < longEntryPrice 且 shortPositionSize < 3）:
+│ │ │ → 市价开空（止盈=longEntryPrice−step→currentShortOrderIds）
+│ │ │ → 累加 positionSize 标记（最多3次）
+│ │ └─ DUAL_SHORT 仓位减少且有反向条件单（newLongFirst > shortEntryPrice
+│ │ 且 < longEntryPrice 且 longPositionSize < 3）:
+│ │ → 市价开多（止盈=shortEntryPrice+step→currentLongOrderIds）
+│ │ → 累加 positionSize 标记（最多3次）
+│ └─ 仓位不变或增加 → 仅更新 positionSize
+└─ size = 0:
+ └─ 清空活跃标记，重置持仓量为0
+
+每次更新后: 截断 currentLongOrderIds / currentShortOrderIds 到最多 5 个元素
```
---
@@ -377,7 +336,7 @@
- 双向持仓: size=0, close=false, autoSize=LONG/SHORT
5. 设杠杆
→ GateKlineWebSocketClient(config.getWsUrl())
- → addChannelHandler x3 → init() → connect()
+ → addChannelHandler x4 → init() → connect()
→ onOpen: handlers依次subscribe → sendPing
→ gridTradeService.startGrid() → state=WAITING_KLINE
```
@@ -389,35 +348,30 @@
→ 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 → 方向区分（一个K线只触发一个方向）
processShortGrid / processLongGrid:
- → 匹配 → 队列转移 → 止盈入队 → 保证金检查
- → 取消对方方向旧条件单(遍历 currentXxxOrderIds)
- → 挂新多空条件单（FuturesPriceTriggeredOrder, price="0"+IOC）
- → 条件满足时挂反向条件单 + 对方止盈入队
+ → 匹配 → 本队补充 → 保证金检查
+ → 挂新条件单（止盈价随 orderId 存入 Map）
+ → 对方守卫：满足条件时挂对方方向新条件单
-条件单被触发成交后 → 仓位推送:
- → 检测净增张数(newUnits = (currentSize - lastSize) / quantity)
- → 逐个消费止盈队列:
- tpPrice = takeProfitQueue.remove(0)（空时兜底: entryPrice ± step）
- executor.placeTakeProfit(tpPrice, rule, plan-close-*-position, ±quantity)
- → 止盈条件单: triggerPrice=止盈价, price="0", tif=IOC, reduce_only=true
+条件单被触发成交后 → futures.orders 推送:
+ → onOrderUpdate(orderId, "finished", "filled")
+ → Map.remove(orderId) 取出止盈价
+ → executor.placeTakeProfit(止盈价, 方向参数, plan-close-*-position)
-额外反向开仓（市价 IOC）:
- → 统一条件: newFirst > shortEntryPrice && newFirst < longEntryPrice && 反向张数 < 3
- → 空仓触发 → 挂反向多仓条件单（触发价=新 short[0]）
- → 多仓触发 → 挂反向空仓条件单（触发价=新 long[0]）
+仓位净减少时 → onPositionUpdate:
+ → 满足反向条件 → 开反向市价单（止盈价 = entryPrice ± step，orderId+止盈价存入 Map）
```
### 阶段 4：停止
@@ -450,7 +404,6 @@
| overallTp | 0.5 USDT | 整体止盈 |
| maxLoss | 7.5 USDT | 最大亏损 |
| quantity | 1 | 下单张数 |
-| reopenMaxRetries | 3 | 补仓最大重试次数（当前版本未使用） |
| gridQueueSize | 50 | 网格价格队列容量 |
| marginRatioLimit | 0.2 | 保证金占初始本金比例上限（20%），超限跳过开仓 |
| contractMultiplier | 0.001 | 合约乘数（单张合约代表的基础资产数量） |
@@ -469,7 +422,7 @@
**回调设计**:
- `openLong`/`openShort`/`placeTakeProfit`/`placeConditionalEntryOrder` 接受 `onSuccess` 和 `onFailure` 两个 `Consumer<String>`
-- REST 调用成功 → 执行 `onSuccess`（标记基底已开、记录 orderId 等）
+- REST 调用成功 → 执行 `onSuccess`（标记基底已开、记录 orderId+止盈价到 Map 等）
- REST 调用失败 → 执行 `onFailure`（当前版本多为 null，依赖 position 推送修正）
### 核心方法
@@ -516,7 +469,7 @@
| initial | price | "0" (市价) | "0" (市价) |
| initial | tif | IOC | IOC |
| initial | reduce_only | false | true |
-| order_type | plan-close-long-position 或 plan-close-short-position | 止盈时才设置 | 止盈时才设置 |
+| order_type | — | 不设置 | plan-close-long-position 或 plan-close-short-position |
---
@@ -533,37 +486,14 @@
private static final String ORDER_TYPE_CLOSE_SHORT = "plan-close-short-position";
```
-**核心数据结构**:
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| shortPriceQueue | `List<BigDecimal>` | 空仓价格队列，降序（大→小），容量 gridQueueSize |
-| longPriceQueue | `List<BigDecimal>` | 多仓价格队列，升序（小→大），容量 gridQueueSize |
-| longTakeProfitQueue | `List<BigDecimal>` | 多仓止盈队列，升序（小→大），仓位推送时消费 |
-| shortTakeProfitQueue | `List<BigDecimal>` | 空仓止盈队列，降序（大→小），仓位推送时消费 |
-| currentLongOrderIds | `List<String>` | 当前多仓条件单 ID 集合（同步列表，含反向单） |
-| currentShortOrderIds | `List<String>` | 当前空仓条件单 ID 集合（同步列表，含反向单） |
-| shortBaseEntryPrice | `BigDecimal` | 基底空头入场价（仅首次记录，用于生成队列） |
-| longBaseEntryPrice | `BigDecimal` | 基底多头入场价（仅首次记录，用于生成队列） |
-| shortEntryPrice | `BigDecimal` | 当前空仓入场价（推送实时更新，加权均价） |
-| longEntryPrice | `BigDecimal` | 当前多仓入场价（推送实时更新，加权均价） |
-| shortPositionSize | `BigDecimal` | 当前空仓持仓量（绝对值） |
-| longPositionSize | `BigDecimal` | 当前多仓持仓量 |
-| baseLongOpened | `boolean` | 基底多头是否已开 |
-| baseShortOpened | `boolean` | 基底空头是否已开 |
-| longActive / shortActive | `boolean` | 多/空方向是否持有仓位 |
-| cumulativePnl | `BigDecimal` | 累计已实现盈亏（平仓推送驱动） |
-| unrealizedPnl | `BigDecimal` | 未实现盈亏（每根K线更新，浮动盈亏） |
-| markPrice | `BigDecimal` | 标记价格（外部注入，MARK_PRICE 模式使用） |
-| initialPrincipal | `BigDecimal` | 初始本金（启动时账户总资产） |
-
**回调方法**:
| 方法 | 触发源 | 逻辑 |
|------|--------|------|
| `onKline(closePrice, timestamp)` | CandlestickChannelHandler | 更新 lastKlinePrice → 计算 unrealizedPnl → WAITING_KLINE 时触发基底双开 → ACTIVE 时方向区分，一个K线只触发一个方向 |
-| `onPositionUpdate(contract, mode, size, entryPrice)` | PositionsChannelHandler | 记录入场价和持仓量 → 基底首次成交记录入场价 + tryGenerateQueues → 非基底仓位净增时从止盈队列消费止盈价挂止盈条件单 |
+| `onPositionUpdate(contract, mode, size, entryPrice)` | PositionsChannelHandler | 基底首次成交记录入场价 + tryGenerateQueues → 仓位净减少时触反向市价单 → Map截断(>5) |
| `onPositionClose(contract, side, pnl)` | PositionClosesChannelHandler | 累加已实现盈亏 → 检查停止条件 |
+| `onOrderUpdate(orderId, status, finishAs)` | OrdersChannelHandler | 条件单成交(finished+filled) → Map.remove 取止盈价 → placeTakeProfit |
**processShortGrid / processLongGrid 核心逻辑**:
@@ -571,11 +501,10 @@
|------|---------------------------|---------------------------|
| 匹配 | 收集 shortPriceQueue 中 > currentPrice 的元素 | 收集 longPriceQueue 中 < currentPrice 的元素 |
| 本队补充 | 尾价 − step 循环递减 × matched.size() 次 | 尾价 + step 循环递增 × matched.size() 次 |
-| 对方转移 | 以多仓首元素为种子，递减 step × i | 以空仓首元素为种子，递增 step × i |
-| 止盈队列 | shortTakeProfitQueue.add(新 short[0] − step)，降序 | longTakeProfitQueue.add(新 long[0] + step)，升序 |
-| 取消旧单 | 遍历 currentLongOrderIds，逐个 cancelConditionalOrder | 遍历 currentShortOrderIds，逐个 cancelConditionalOrder |
-| 挂新条件单 | 空仓条件单(触发价=新 short[0]) + 多仓条件单(触发价=新 long[0]) | 多仓条件单(触发价=新 long[0]) + 空仓条件单(触发价=新 short[0]) |
-| 反向条件单 | 新 short[0] 在[shortEntryPrice, longEntryPrice]间且 longPositionSize<3 → 反向多单 | 新 long[0] 在[shortEntryPrice, longEntryPrice]间且 shortPositionSize<3 → 反向空单 |
+| 对方队列 | 不再更新（队列转移已移除） | 不再更新（队列转移已移除） |
+| 保证金检查 | marginRatio ≥ 20% 则跳过挂单 | 同左 |
+| 挂新条件单 | 空仓条件单（止盈价=新short[0]−step→currentShortOrderIds） | 多仓条件单（止盈价=新long[0]+step→currentLongOrderIds） |
+| 对方守卫 | newLongFirst + step×2 < longEntryPrice → 挂多仓条件单 | newShortFirst − step×2 > shortEntryPrice → 挂空仓条件单 |
**未实现盈亏计算** (`updateUnrealizedPnl()`):
@@ -590,22 +519,10 @@
- `LAST_PRICE`：使用最新成交价（`lastKlinePrice`，每根 K 线更新）
- `MARK_PRICE`：使用标记价格（通过 `setMarkPrice()` 外部注入，如未注入则回退到最新成交价）
-入场价和持仓量由 `onPositionUpdate` 实时推送更新。
-
**保证金安全阀** (`isMarginSafe()`):
- 实时查询 `positionInitialMargin / initialPrincipal`
- 比例 ≥ marginRatioLimit（默认20%）→ 跳过开仓，队列照常更新
- REST 查询失败 → 默认放行（避免因查询异常阻塞策略）
-
-**止盈计算**:
-
-| 方向 | 止盈价来源 | 兜底价 | order_type | rule |
-|------|-----------|--------|------------|------|
-| 多头 TP | longTakeProfitQueue.remove(0) | longEntryPrice + step | `plan-close-long-position` | NUMBER_1(≥触发价) |
-| 空头 TP | shortTakeProfitQueue.remove(0) | shortEntryPrice − step | `plan-close-short-position` | NUMBER_2(≤触发价) |
-
-> 止盈价从止盈队列消费。止盈队列由 K线触发时新增元素（新 queue[0] ± step），仓位推送时按每批 quantity 张数逐个消费。
-> 止盈队列空时兜底用当前入场价 ± step。每批挂独立止盈条件单，互不覆盖。
**REST API 调用**:
@@ -614,6 +531,53 @@
| 获取用户ID | `GET /account/detail` | `AccountApi.getAccountDetail()` | |
| 切持仓模式 | `POST /futures/usdt/set_position_mode` | `FuturesApi.setPositionMode()` | |
| 查仓位 | `GET /futures/usdt/positions` | `FuturesApi.listPositions()` | 遍历所有仓位，按合约过滤 |
-| 市价平仓 | `POST /futures/usdt/orders` | `FuturesApi.createFuturesOrder()` | reduce_only, IOC。双向: size=0+close=false+autoSize |
+| 市价平仓 | `POST /futures/usdt/orders` | `FuturesApi.createFuturesOrder()` | reduce_only, IOC |
| 设杠杆 | `POST /futures/usdt/dual_comp/positions/{contract}/leverage` | `FuturesApi.updateDualModePositionLeverageCall()` | 双向模式专用 |
-| 查账户 | `GET /futures/usdt/accounts` | `FuturesApi.listFuturesAccounts()` | 获取初始
\ No newline at end of file
+| 查账户 | `GET /futures/usdt/accounts` | `FuturesApi.listFuturesAccounts()` | 获取初始本金 |
+| 查市价 | `GET /futures/usdt/order_book` | `FuturesApi.listFuturesOrderBook()` | 获取合约实时市价（用于市价单 price="0" 的参照） |
+
+---
+
+## GateChannelHandler 接口体系
+
+```
+GateChannelHandler (接口)
+ ├── CandlestickChannelHandler (公开频道)
+ └── AbstractPrivateChannelHandler (私有频道基类: HMAC-SHA512)
+ ├── PositionsChannelHandler
+ ├── PositionClosesChannelHandler
+ └── OrdersChannelHandler
+```
+
+- **subscribe**: 发送订阅请求。私有 Handler 自动附加 auth 字段
+- **unsubscribe**: 发送取消订阅请求（私有频道也带签名认证）
+- **handleMessage**: 解析推送数据并回调 GateGridTradeService，返回 true 表示已处理
+- 消息路由: update/all 事件 → 遍历 channelHandlers → handler 内部二次匹配 channel 名 → 匹配成功回调并停止遍历
+
+### PositionsChannelHandler 完整推送字段（20个）
+
+| 字段 | 类型 | 描述 |
+|------|------|------|
+| contract | String | 合约名称 |
+| mode | String | 持仓模式：dual_long / dual_short |
+| size | String/Integer | 合约张数（正=多头，负=空头） |
+| entry_price | Float | 开仓均价 |
+| cross_leverage_limit | Float | 全仓模式下的杠杆倍数上限 |
+| history_pnl | Float | 已平仓的仓位总盈亏 |
+| history_point | Float | 已平仓的点卡总盈亏 |
+| last_close_pnl | Float | 最近一次平仓的盈亏 |
+| leverage | Integer | 杠杆倍数（0=全仓，正数=逐仓） |
+| leverage_max | Integer | 当前风险限额下允许的最大杠杆倍数 |
+| liq_price | Float | 爆仓价格 |
+| maintenance_rate | Float | 当前风险限额下维持保证金比例 |
+| margin | Float | 保证金 |
+| realised_pnl | Float | 已实现盈亏 |
+| realised_point | Float | 点卡已实现盈亏 |
+| risk_limit | Integer | 风险限额 |
+| time | Integer | 更新 unix 时间戳（秒） |
+| time_ms | Integer | 更新 unix 时间戳（毫秒） |
+| user | String | 用户 ID |
+| update_id | Integer | 消息序列号，每次推送 order 后自增1 |
+
+> 以上 20 个字段在 PositionsChannelHandler.handleMessage() 中通过 SLF4J 日志全部输出。
+> 回调给 GateGridTradeService.onPositionUpdate() 的仅有 mode、size、entryPrice 三个核心字段。
--
Gitblit v1.9.1