From 4e8401a3b2022b7f4251035afa82baf0db5eca9f Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Thu, 04 Jun 2026 11:32:29 +0800
Subject: [PATCH] fix(gateApi): 调整网格交易参数配置
---
src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java | 139 +++++++++++++++++++++++++++++++++++++---------
1 files changed, 112 insertions(+), 27 deletions(-)
diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java b/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
index b65d0aa..9b207cc 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java
@@ -1,46 +1,63 @@
package com.xcong.excoin.modules.gateApi;
import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
/**
- * Gate 模块统一配置。
+ * Gate 交易模块全局配置，策略的唯一参数入口。
*
- * <p>通过 Builder 模式集中管理所有运行参数，避免参数散落在多个文件中。
- * 提供 REST API 和 WebSocket 地址的自动环境切换（测试网/生产网）。
+ * <h3>定位</h3>
+ * 通过 Builder 模式将所有运行参数集中管理，避免策略参数散落在多个类中。
+ * 运行时动态参数（step、gridElements、baseLongTraderParam、baseShortTraderParam）
+ * 由 {@link GateGridTradeService} 在策略执行过程中写入。
*
- * <h3>使用示例</h3>
- * <pre>
- * GateConfig config = GateConfig.builder()
- * .apiKey("...")
- * .apiSecret("...")
- * .contract("XAU_USDT")
- * .leverage("100")
- * .gridRate(new BigDecimal("0.0035"))
- * .contractMultiplier("0.001")
- * .isProduction(false)
- * .build();
+ * <h3>参数分类</h3>
+ * <table>
+ * <tr><th>类别</th><th>参数</th><th>用途</th></tr>
+ * <tr><td>认证</td><td>apiKey, apiSecret</td><td>REST/WS 签名认证</td></tr>
+ * <tr><td>交易标的</td><td>contract, leverage, quantity, contractMultiplier</td><td>合约、杠杆、张数、乘数</td></tr>
+ * <tr><td>持仓</td><td>marginMode, positionMode</td><td>全仓/逐仓、单向/双向</td></tr>
+ * <tr><td>网格策略</td><td>gridRate, gridQueueSize, priceScale</td><td>间距比例、队列容量、价格精度（交易所tick）</td></tr>
+ * <tr><td>止盈止损</td><td>overallTp, maxLoss</td><td>整体止盈/亏损阈值（USDT），触发后策略停止</td></tr>
+ * <tr><td>风控</td><td>marginRatioLimit, reopenMaxRetries</td><td>保证金占比上限、补仓重试次数</td></tr>
+ * <tr><td>盈亏计算</td><td>contractMultiplier, unrealizedPnlPriceMode</td><td>合约乘数、未实现盈亏计价模式</td></tr>
+ * <tr><td>运行时</td><td>step, gridElements, baseLongTraderParam, baseShortTraderParam</td><td>由策略动态填充</td></tr>
+ * </table>
*
- * String restUrl = config.getRestBasePath(); // 自动返回测试网或生产网地址
- * String wsUrl = config.getWsUrl();
- * </pre>
- *
- * <h3>默认值</h3>
+ * <h3>priceScale 说明</h3>
+ * 价格精度表示交易所允许的最小价格单位的小数位数：
* <ul>
- * <li>合约: BTC_USDT, 杠杆: 10x, 全仓, 双向持仓</li>
- * <li>网格间距: 0.35%, 队列容量: 50, 保证金比例上限: 20%</li>
- * <li>止盈: 0.5 USDT, 亏损上限: 7.5 USDT</li>
- * <li>数量: 1 张, 合约乘数: 0.001, 环境: 测试网</li>
+ * <li>XAU_USDT: tick=0.1 → priceScale=1</li>
+ * <li>ETH_USDT: tick=0.01 → priceScale=2</li>
* </ul>
+ * 所有价格计算必须对齐到 tick 整数倍，否则 Gate API 返回
+ * {@code invalid argument: trigger.price price is not an integer multiple of a price unit}。
+ *
+ * <h3>gridElements 生命周期</h3>
+ * <ol>
+ * <li>项目启动时初始化为空 ArrayList</li>
+ * <li>{@code tryGenerateQueues()} 中通过 {@code updateGridElements()} 填充，同时触发
+ * {@link GridElement#rebuildIndex(List)} 建立全局 O(1) 索引</li>
+ * <li>每次挂单/止盈操作后通过 {@link GridElement#refreshIndices()} 更新索引</li>
+ * </ol>
*
* @author Administrator
*/
public class GateConfig {
- /** 未实现盈亏计价模式 */
+ /**
+ * 未实现盈亏（unrealizedPnl）计价模式。
+ *
+ * <ul>
+ * <li>{@link #LAST_PRICE} — 按最新成交价计算，变动快、更贴近实际平仓价</li>
+ * <li>{@link #MARK_PRICE} — 按标记价格计算，变动平稳、过滤市场噪音</li>
+ * </ul>
+ */
public enum PnLPriceMode {
- /** 按最新成交价计算 */
+ /** 按最新成交价计算未实现盈亏 */
LAST_PRICE,
- /** 按标记价格计算 */
+ /** 按标记价格计算未实现盈亏，需通过 {@link GateGridTradeService#setMarkPrice(BigDecimal)} 注入 */
MARK_PRICE
}
@@ -64,6 +81,10 @@
private final BigDecimal maxLoss;
/** 下单数量（合约张数） */
private final String quantity;
+ /** 基底开仓张数（初始化时多空各开的张数，如 "10"） */
+ private final String baseQuantity;
+ /** 预期收益（USDT），unrealisedPnl + available > 初始本金 + 此值时重置 */
+ private final BigDecimal expectedProfit;
/** 是否为生产环境 */
private final boolean isProduction;
/** 补仓最大重试次数 */
@@ -74,8 +95,18 @@
private final BigDecimal marginRatioLimit;
/** 合约乘数（单张合约代表的基础资产数量，如 BTC_USDT=0.001, ETH_USDT=0.01） */
private final BigDecimal contractMultiplier;
+ /** 价格精度（交易所价格的最小小数位数，如 XAU_USDT=1 表示 0.1 精度，ETH_USDT=2 表示 0.01 精度） */
+ private final int priceScale;
/** 未实现盈亏计价模式：最新价 / 标记价格 */
private final PnLPriceMode unrealizedPnlPriceMode;
+ /** 网格绝对步长（shortBaseEntryPrice × gridRate），运行时由队列生成逻辑设置 */
+ private BigDecimal step;
+ /** 网格元素列表，由队列初始化时同步填充，包含完整的多空仓挂单状态 */
+ private volatile List<GridElement> gridElements = new ArrayList<>();
+ /** 基座多头挂单参数，在基座成交后由 tryGenerateQueues 填充 */
+ private TraderParam baseLongTraderParam;
+ /** 基座空头挂单参数，在基座成交后由 tryGenerateQueues 填充 */
+ private TraderParam baseShortTraderParam;
private GateConfig(Builder builder) {
this.apiKey = builder.apiKey;
@@ -88,11 +119,14 @@
this.overallTp = builder.overallTp;
this.maxLoss = builder.maxLoss;
this.quantity = builder.quantity;
+ this.baseQuantity = builder.baseQuantity;
+ this.expectedProfit = builder.expectedProfit;
this.isProduction = builder.isProduction;
this.reopenMaxRetries = builder.reopenMaxRetries;
this.gridQueueSize = builder.gridQueueSize;
this.marginRatioLimit = builder.marginRatioLimit;
this.contractMultiplier = builder.contractMultiplier;
+ this.priceScale = builder.priceScale;
this.unrealizedPnlPriceMode = builder.unrealizedPnlPriceMode;
}
@@ -155,6 +189,10 @@
public BigDecimal getMaxLoss() { return maxLoss; }
/** @return 每次下单的张数（如 "1" 表示 1 张合约） */
public String getQuantity() { return quantity; }
+ /** @return 基底开仓张数（初始化时多空各开的张数，如 "10"） */
+ public String getBaseQuantity() { return baseQuantity; }
+ /** @return 预期收益（USDT），unrealisedPnl + available > 初始本金 + 此值时重置 */
+ public BigDecimal getExpectedProfit() { return expectedProfit; }
/** @return 网格价格队列的容量上限（超出时截断尾部） */
public int getGridQueueSize() { return gridQueueSize; }
@@ -169,8 +207,39 @@
/** @return 合约乘数（单张合约代表的基础资产数量，如 ETH_USDT=0.01） */
public BigDecimal getContractMultiplier() { return contractMultiplier; }
+ /** @return 价格精度（交易所价格的小数位数，如 1=0.1精度，2=0.01精度），用于价格四舍五入 */
+ public int getPriceScale() { return priceScale; }
/** @return 未实现盈亏计价模式：LAST_PRICE（最新成交价）/ MARK_PRICE（标记价格） */
public PnLPriceMode getUnrealizedPnlPriceMode() { return unrealizedPnlPriceMode; }
+
+ // ==================== 运行时参数 ====================
+
+ /** @return 网格绝对步长（shortBaseEntryPrice × gridRate），运行时设置 */
+ public BigDecimal getStep() { return step; }
+ /** 设置网格绝对步长（由 generateShortQueue 在运行时计算并注入） */
+ public void setStep(BigDecimal step) { this.step = step; }
+
+ // ==================== 网格元素列表 ====================
+
+ /** @return 网格元素列表（队列初始化后填充），线程不安全，仅由策略线程单线程写入 */
+ public List<GridElement> getGridElements() { return gridElements; }
+ /** 设置网格元素列表（由队列生成逻辑写入），同时重建全局 ID 索引 */
+ public void setGridElements(List<GridElement> gridElements) {
+ this.gridElements = gridElements;
+ GridElement.rebuildIndex(gridElements);
+ }
+
+ // ==================== 基座挂单参数 ====================
+
+ /** @return 基座多头挂单参数 */
+ public TraderParam getBaseLongTraderParam() { return baseLongTraderParam; }
+ /** 设置基座多头挂单参数（由 tryGenerateQueues 在基座成交后填充） */
+ public void setBaseLongTraderParam(TraderParam baseLongTraderParam) { this.baseLongTraderParam = baseLongTraderParam; }
+
+ /** @return 基座空头挂单参数 */
+ public TraderParam getBaseShortTraderParam() { return baseShortTraderParam; }
+ /** 设置基座空头挂单参数（由 tryGenerateQueues 在基座成交后填充） */
+ public void setBaseShortTraderParam(TraderParam baseShortTraderParam) { this.baseShortTraderParam = baseShortTraderParam; }
// ==================== 环境 ====================
@@ -212,16 +281,22 @@
private BigDecimal maxLoss = new BigDecimal("7.5");
/** 每次下单张数，默认 "1" */
private String quantity = "1";
+ /** 基底开仓张数，默认 "10"（初始化时多空各开10张） */
+ private String baseQuantity = "10";
+ /** 预期收益（USDT），默认 0.5 */
+ private BigDecimal expectedProfit = new BigDecimal("0.5");
/** 是否为生产环境，默认 false（测试网） */
private boolean isProduction = false;
/** 补仓最大重试次数，默认 3 */
private int reopenMaxRetries = 3;
/** 网格队列容量，默认 50 */
- private int gridQueueSize = 50;
+ private int gridQueueSize = 300;
/** 保证金占初始本金比例上限，默认 0.2（20%） */
private BigDecimal marginRatioLimit = new BigDecimal("0.2");
/** 合约乘数，默认 0.001 */
private BigDecimal contractMultiplier = new BigDecimal("0.001");
+ /** 价格精度（交易所价格的小数位数），默认 1（0.1 精度） */
+ private int priceScale = 1;
/** 未实现盈亏计价模式，默认 LAST_PRICE（最新成交价） */
private PnLPriceMode unrealizedPnlPriceMode = PnLPriceMode.LAST_PRICE;
@@ -245,12 +320,22 @@
public Builder maxLoss(BigDecimal maxLoss) { this.maxLoss = maxLoss; return this; }
/** 设置每次下单张数 */
public Builder quantity(String quantity) { this.quantity = quantity; return this; }
+ /** 设置基底开仓张数 */
+ public Builder baseQuantity(String baseQuantity) { this.baseQuantity = baseQuantity; return this; }
+ /** 设置预期收益（USDT） */
+ public Builder expectedProfit(BigDecimal expectedProfit) { this.expectedProfit = expectedProfit; return this; }
/** 设置环境（true=实盘生产网 / false=模拟盘测试网） */
public Builder isProduction(boolean isProduction) { this.isProduction = isProduction; return this; }
/** 设置补仓最大重试次数 */
public Builder reopenMaxRetries(int reopenMaxRetries) { this.reopenMaxRetries = reopenMaxRetries; return this; }
/** 设置合约乘数（单张合约代表的基础资产数量） */
public Builder contractMultiplier(BigDecimal contractMultiplier) { this.contractMultiplier = contractMultiplier; return this; }
+ /** 设置价格精度（交易所价格的小数位数，如 1=0.1精度，2=0.01精度） */
+ public Builder priceScale(int priceScale) { this.priceScale = priceScale; return this; }
+ /** 设置保证金占初始本金比例上限 */
+ public Builder marginRatioLimit(BigDecimal marginRatioLimit) { this.marginRatioLimit = marginRatioLimit; return this; }
+ /** 设置网格队列容量 */
+ public Builder gridQueueSize(int gridQueueSize) { this.gridQueueSize = gridQueueSize; return this; }
/** 设置未实现盈亏计价模式 */
public Builder unrealizedPnlPriceMode(PnLPriceMode mode) { this.unrealizedPnlPriceMode = mode; return this; }
--
Gitblit v1.9.1