From 98986bf100201ad41843cbba52d803911c7277f0 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Sat, 09 May 2026 16:25:09 +0800
Subject: [PATCH] fix(gateApi): 修正计划订单类型常量命名
---
src/main/java/com/xcong/excoin/modules/gateApi/gateApi-logic.md | 49 ++++++++++++++++++++++++++-----------------------
1 files changed, 26 insertions(+), 23 deletions(-)
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 e98d14c..c00b126 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
@@ -141,12 +141,12 @@
### 网格队列生成
-以基底入场价为基准，按 `gridRate` 步长生成 N 个价格（N = gridQueueSize，默认50）：
+以基底入场价为基准，按 `gridRate`（百分比步长）生成 N 个价格（N = gridQueueSize，默认50）：
| 队列 | 计算方式 | 排序 |
|------|---------|------|
-| 空仓队列 shortPriceQueue | 基底空入场价 - gridRate × i (i=1..N) | 降序（大→小） |
-| 多仓队列 longPriceQueue | 基底多入场价 + gridRate × i (i=1..N) | 升序（小→大） |
+| 空仓队列 shortPriceQueue | 基底空入场价 × (1 − gridRate × i) (i=1..N) | 降序（大→小） |
+| 多仓队列 longPriceQueue | 基底多入场价 × (1 + gridRate × i) (i=1..N) | 升序（小→大） |
### K线触发网格
@@ -158,7 +158,7 @@
│ ├─ 保证金检查: positionInitialMargin / initialPrincipal < marginRatioLimit(20%)
│ │ ├─ 安全 → openShort 开空单（成交后仓位推送会自动设止盈）
│ │ └─ 超限 → 跳过开仓，队列照常更新
-│ ├─ 空仓队列: 移除匹配元素，尾部补充新价格（按步长递减）
+│ ├─ 空仓队列: 移除匹配元素，尾部补充新价格（尾价 × (1 − gridRate)）
│ └─ 多仓队列: 接收匹配元素，升序排列，截断到 gridQueueSize
│
└─ processLongGrid: 当前价 > 多仓队列元素（价格涨超了队列中的低价）
@@ -166,22 +166,24 @@
├─ 保证金检查: 同上
│ ├─ 安全 → openLong 开多单
│ └─ 超限 → 跳过开仓
- ├─ 多仓队列: 移除匹配元素，尾部补充新价格（按步长递增）
+ ├─ 多仓队列: 移除匹配元素，尾部补充新价格（尾价 × (1 + gridRate)）
└─ 空仓队列: 接收匹配元素，降序排列，截断到 gridQueueSize
```
### 队列转移示意
```
-初始状态:
- 空仓队列: [100, 99, 98, 97] (降序)
- 多仓队列: [102, 103, 104, 105] (升序)
+ETH_USDT, gridRate=0.0035, 基底空入场价=2275, 基底多入场价=2275:
-价格跌到 98.5 → processShortGrid 触发:
- 匹配: [100, 99]（都 > 98.5）
+初始状态:
+ 空仓队列: [2267.1, 2270.0, 2272.5, 2275.0] (降序，base×0.9965, base×0.993...)
+ 多仓队列: [2275.0, 2277.5, 2280.0, 2282.5] (升序，base×1.0035, base×1.007...)
+
+价格跌到 2271 → processShortGrid 触发:
+ 匹配: [2275.0, 2272.5]（都 > 2271）
- 空仓队列: 移除[100,99] → [98,97] → 补充[96,95] → [98,97,96,95]
- 多仓队列: 接收[100,99] → [100,99,102,103,104,105] → 截断到4 → [102,103,104,105]
+ 空仓队列: 移除[2275.0,2272.5] → [2270.0,2267.1] → 补充[2267.1×0.9965≈2259.1, 2259.1×0.9965≈2251.2] → [2270.0,2267.1,2259.1,2251.2]
+ 多仓队列: 接收[2275.0,2272.5] → 合并后截断到4 → [2272.5,2275.0,2277.5,2280.0]
```
---
@@ -228,12 +230,13 @@
每根K线 → onKline → updateUnrealizedPnl → processShortGrid + processLongGrid
仓位推送（每次开仓成交后自动触发）:
- → DUAL_LONG, size>0, 非基底 → 设多头止盈单 entryPrice × (1+gridRate)
- → DUAL_SHORT, size<0, 非基底 → 设空头止盈单 entryPrice × (1-gridRate)
+ → DUAL_LONG, size>0, 非基底 → 设多头止盈单：止盈价=entryPrice×(1+gridRate)，平仓张数=quantity（负=平多）
+ → DUAL_SHORT, size<0, 非基底 → 设空头止盈单：止盈价=entryPrice×(1−gridRate)，平仓张数=quantity（正=平空）
```
> 止盈由 Gate 服务端条件单自动执行。服务端监控价格，达到触发价后自动平仓。
-> 平仓后仓位变为0，盈亏通过 position_closes 频道推送到 cumulativePnl。
+> 每次网格触发开仓 quantity 张，只在该批张数上设止盈，与之前已设的止盈单互不影响。
+> 平仓后仓位减少 quantity 张，盈亏通过 position_closes 频道推送到 cumulativePnl。
### 阶段 4：停止
@@ -290,7 +293,7 @@
|------|------|
| `openLong(qty, onSuccess, onFailure)` | 异步 IOC 市价开多，双回调 |
| `openShort(qty, onSuccess, onFailure)` | 异步 IOC 市价开空，双回调 |
-| `placeTakeProfit(trigger, rule, type, auto)` | 异步条件单。已存在则清除旧单重试 |
+| `placeTakeProfit(trigger, rule, type, size)` | 异步止盈条件单。size 为显式平仓张数（正=平空，负=平多），多次调用互不影响 |
| `cancelAllPriceTriggeredOrders()` | 清除所有条件单 |
| `shutdown()` | 等待10秒，超时强制关闭 |
@@ -304,8 +307,6 @@
**关键常量**:
```java
-private static final String AUTO_SIZE_LONG = "close_long";
-private static final String AUTO_SIZE_SHORT = "close_short";
private static final String ORDER_TYPE_CLOSE_LONG = "close-long-position";
private static final String ORDER_TYPE_CLOSE_SHORT = "close-short-position";
```
@@ -332,7 +333,7 @@
**回调方法**:
- `onKline(closePrice)`: 更新 lastKlinePrice → 计算 unrealizedPnl → WAITING_KLINE 时触发基底双开，ACTIVE 时驱动 processShortGrid+processLongGrid
-- `onPositionUpdate(contract, mode, size, entryPrice)`: 记录当前入场价和持仓量 → 有仓位时标记活跃+设止盈，无仓位时清空持仓量并标记不活跃
+- `onPositionUpdate(contract, mode, size, entryPrice)`: 记录当前入场价和持仓量 → 基底：首次成交记录入场价、生成队列；非基底：按 quantity 张数创建独立止盈条件单。无仓位时清空持仓量并标记不活跃
- `onPositionClose(contract, side, pnl)`: 累加已实现盈亏，检查停止条件
**未实现盈亏计算** (`updateUnrealizedPnl()`):
@@ -357,10 +358,12 @@
**止盈计算**:
-| 方向 | 公式 | order_type | auto_size | rule |
+| 方向 | 公式 | order_type | size（平仓张数） | rule |
|------|------|------------|-----------|------|
-| 多头 TP | entry × (1+gridRate) | `close-long-position` | `close_long` | NUMBER_1(≥触发价) |
-| 空头 TP | entry × (1-gridRate) | `close-short-position` | `close_short` | NUMBER_2(≤触发价) |
+| 多头 TP | entry × (1+gridRate) | `close-long-position` | `-quantity`（负=平多） | NUMBER_1(≥触发价) |
+| 空头 TP | entry × (1−gridRate) | `close-short-position` | `+quantity`（正=平空） | NUMBER_2(≤触发价) |
+
+> 止盈单使用显式张数而非 autoSize。每次网格触发开仓 quantity 张，只为该批张数创建独立的条件单，多个止盈单之间互不覆盖。
**REST API 调用**:
@@ -374,7 +377,7 @@
| 查账户 | `GET /futures/usdt/accounts` | `FuturesApi.listFuturesAccounts()` | 获取初始本金和保证金 |
| 清除条件单 | `DELETE /futures/usdt/price_orders` | `FuturesApi.cancelPriceTriggeredOrderList()` | |
| 市价单 | `POST /futures/usdt/orders` | `FuturesApi.createFuturesOrder()` | price=0, tif=IOC |
-| 条件单 | `POST /futures/usdt/price_orders` | `FuturesApi.createPriceTriggeredOrder()` | strategy=0, price_type=0, expiration=0 |
+| 条件单 | `POST /futures/usdt/price_orders` | `FuturesApi.createPriceTriggeredOrder()` | strategy=0, price_type=0, expiration=0, size=显式张数（非autoSize），多次调用互不冲突 |
**初始化顺序** (`init()`):
```
--
Gitblit v1.9.1