feat(gate): 添加加仓启动阈值配置功能

Administrator

2026-08-10 423f15ff32cd88abcbb703b15dcc66fa2ed05602

 src/main/java/com/xcong/excoin/modules/gateApi/GateConfig.java

@@ -1,43 +1,46 @@
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>
 * <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>
 *
 * <h3>priceScale 说明</h3>
 * 价格精度表示交易所允许的最小价格单位的小数位数：
 * <ul>
 *   <li><b>网格参数</b>：gridRate（比例间距）、step（绝对步长 = shortBaseEntryPrice × gridRate，运行时计算）、
 *       gridQueueSize（队列容量）</li>
 *   <li><b>止盈止损</b>：overallTp（整体止盈 USDT）、maxLoss（最大亏损 USDT）</li>
 *   <li><b>风险控制</b>：marginRatioLimit（保证金占比上限，超限跳过开仓）、leverage（杠杆）、
 *       marginMode（全仓/逐仓）、positionMode（单向/双向）</li>
 *   <li><b>盈亏计算</b>：contractMultiplier（合约乘数）、unrealizedPnlPriceMode（计价模式：最新价/标记价）</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>使用示例</h3>
 * <pre>
 *   GateConfig config = GateConfig.builder()
 *       .apiKey("...")
 *       .apiSecret("...")
 *       .contract("ETH_USDT")
 *       .leverage("100")
 *       .gridRate(new BigDecimal("0.0035"))
 *       .contractMultiplier("0.01")
 *       .isProduction(false)
 *       .build();
 * </pre>
 *
 * <h3>默认值</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>
 * </ul>
 * <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
 */
@@ -78,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;
    /** 补仓最大重试次数 */
@@ -88,10 +95,40 @@
    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;
    /** 最大持仓张数（单方向），0=不限制 */
    private final int maxPositionSize;
    /** 策略重启跨度阈值：多空两边止盈触发数量均达到此值后触发重启，0=禁用 */
    private final int restartGridSpan;
    /** 止损阶梯次数：止损触发次数≤该值时挂单量=止损次数，超过后恢复默认逻辑。0=禁用，默认 0 */
    private final int stopLossCount;
    /** 止盈网格跨度：相邻止盈单跨越的网格数量，默认 2（即隔一格挂一个止盈单） */
    private final int takeProfitGridSpan;
    /** 价格驱动开关：true=启用K线推送中的价格驱动逻辑，false=禁用。默认 true */
    private final boolean priceDriveEnabled;
    /** 策略运行轮数：达到盈利后重启算一轮，达到上限后不再重启。0=不限轮数 */
    private final int rounds;
    /** 止损次数统计方式："single"=单向分别统计 / "dual"=双向统一统计，默认 "dual" */
    private final String stopLossCountMode;
    /** 加仓间隔：每隔多少次止损触发一次加仓，默认 3 */
    private final int addPositionInterval;
    /** 加仓数量：每次加仓追加的张数，默认 1 */
    private final int addPositionQuantity;
    /** 单边最大仓位量：单向持仓张数上限，超出则按上限挂单，0=不限制 */
    private final int maxPositionPerSide;
    /** 加仓启动阈值：前N次止损不触发加仓，默认 1（第1次止损不加仓，第2次起按公式计算） */
    private final int addPositionStartThreshold;
    /** 网格绝对步长（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;
@@ -104,12 +141,26 @@
        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;
        this.maxPositionSize = builder.maxPositionSize;
        this.restartGridSpan = builder.restartGridSpan;
        this.stopLossCount = builder.stopLossCount;
        this.takeProfitGridSpan = builder.takeProfitGridSpan;
        this.priceDriveEnabled = builder.priceDriveEnabled;
        this.rounds = builder.rounds;
        this.stopLossCountMode = builder.stopLossCountMode;
        this.addPositionInterval = builder.addPositionInterval;
        this.addPositionQuantity = builder.addPositionQuantity;
        this.maxPositionPerSide = builder.maxPositionPerSide;
        this.addPositionStartThreshold = builder.addPositionStartThreshold;
    }

    // ==================== REST/WS 地址 ====================
@@ -171,6 +222,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; }

@@ -185,8 +240,32 @@

    /** @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 最大持仓张数（单方向），0=不限制 */
    public int getMaxPositionSize() { return maxPositionSize; }
    /** @return 策略重启跨度阈值：多空两边止盈触发数均达到此值后触发重启，0=禁用 */
    public int getRestartGridSpan() { return restartGridSpan; }
    /** @return 止损阶梯次数：止损触发次数≤该值时挂单量=止损次数,超过后恢复默认逻辑。0=禁用 */
    public int getStopLossCount() { return stopLossCount; }
    /** @return 止盈网格跨度：相邻止盈单跨越的网格数量，默认 2 */
    public int getTakeProfitGridSpan() { return takeProfitGridSpan; }
    /** @return 价格驱动开关：true=启用K线推送中的价格驱动逻辑，false=禁用 */
    public boolean isPriceDriveEnabled() { return priceDriveEnabled; }
    /** @return 策略运行轮数上限，0=不限 */
    public int getRounds() { return rounds; }
    /** @return 止损次数统计方式："single"=单向分别统计 / "dual"=双向统一统计 */
    public String getStopLossCountMode() { return stopLossCountMode; }
    /** @return 加仓间隔：每隔多少次止损触发一次加仓 */
    public int getAddPositionInterval() { return addPositionInterval; }
    /** @return 加仓数量：每次加仓追加的张数 */
    public int getAddPositionQuantity() { return addPositionQuantity; }
    /** @return 单边最大仓位量：单向持仓张数上限，0=不限制 */
    public int getMaxPositionPerSide() { return maxPositionPerSide; }
    /** @return 加仓启动阈值：前N次止损不触发加仓 */
    public int getAddPositionStartThreshold() { return addPositionStartThreshold; }

    // ==================== 运行时参数 ====================

@@ -194,6 +273,28 @@
    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; }

    // ==================== 环境 ====================

@@ -235,18 +336,46 @@
        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;
        /** 最大持仓张数（单方向），默认 0=不限制 */
        private int maxPositionSize = 0;
        /** 策略重启跨度阈值：多空两边止盈触发数量均达到此值后触发重启，默认 0=禁用 */
        private int restartGridSpan = 0;
        /** 止损阶梯次数：止损触发次数≤该值时挂单量=止损次数，超过后恢复默认逻辑。0=禁用，默认 0 */
        private int stopLossCount = 0;
        /** 止盈网格跨度：相邻止盈单跨越的网格数量，默认 2 */
        private int takeProfitGridSpan = 2;
        /** 价格驱动开关：true=启用K线推送中的价格驱动逻辑，false=禁用。默认 true */
        private boolean priceDriveEnabled = true;
        /** 策略运行轮数上限，0=不限轮数。默认 0 */
        private int rounds = 0;
        /** 止损次数统计方式："single"=单向分别统计 / "dual"=双向统一统计，默认 "dual" */
        private String stopLossCountMode = "dual";
        /** 加仓间隔：每隔多少次止损触发一次加仓，默认 3 */
        private int addPositionInterval = 3;
        /** 加仓数量：每次加仓追加的张数，默认 1 */
        private int addPositionQuantity = 1;
        /** 单边最大仓位量：单向持仓张数上限，超出则按上限挂单，0=不限制 */
        private int maxPositionPerSide = 0;
        /** 加仓启动阈值：前N次止损不触发加仓，调整后的 effectiveCount = max(0, count - threshold)。默认 1 */
        private int addPositionStartThreshold = 1;

        /** 设置 API Key */
        public Builder apiKey(String apiKey) { this.apiKey = apiKey; return this; }
@@ -268,14 +397,46 @@
        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; }
        /** 设置最大持仓张数（单方向），0=不限制 */
        public Builder maxPositionSize(int maxPositionSize) { this.maxPositionSize = maxPositionSize; return this; }
        /** 设置策略重启跨度阈值：多空两边止盈触发数均达到此值后触发重启，0=禁用 */
        public Builder restartGridSpan(int restartGridSpan) { this.restartGridSpan = restartGridSpan; return this; }
        /** 设置止损阶梯次数：止损触发次数≤该值时挂单量=止损次数，超过后恢复默认逻辑。0=禁用 */
        public Builder stopLossCount(int stopLossCount) { this.stopLossCount = stopLossCount; return this; }
        /** 设置止盈网格跨度：相邻止盈单跨越的网格数量，默认 2 */
        public Builder takeProfitGridSpan(int takeProfitGridSpan) { this.takeProfitGridSpan = takeProfitGridSpan; return this; }
        /** 设置价格驱动开关：true=启用K线推送中的价格驱动逻辑，false=禁用 */
        public Builder priceDriveEnabled(boolean priceDriveEnabled) { this.priceDriveEnabled = priceDriveEnabled; return this; }
        /** 设置策略运行轮数上限：达到盈利后重启计数，达到此值后不再重启。0=不限 */
        public Builder rounds(int rounds) { this.rounds = rounds; return this; }
        /** 设置止损次数统计方式："single"=单向分别统计 / "dual"=双向统一统计 */
        public Builder stopLossCountMode(String stopLossCountMode) { this.stopLossCountMode = stopLossCountMode; return this; }
        /** 设置加仓间隔：每隔多少次止损触发一次加仓 */
        public Builder addPositionInterval(int addPositionInterval) { this.addPositionInterval = addPositionInterval; return this; }
        /** 设置加仓数量：每次加仓追加的张数 */
        public Builder addPositionQuantity(int addPositionQuantity) { this.addPositionQuantity = addPositionQuantity; return this; }
        /** 设置单边最大仓位量：单向持仓张数上限，0=不限制 */
        public Builder maxPositionPerSide(int maxPositionPerSide) { this.maxPositionPerSide = maxPositionPerSide; return this; }
        /** 设置加仓启动阈值：前N次止损不触发加仓，0=立即启动 */
        public Builder addPositionStartThreshold(int addPositionStartThreshold) { this.addPositionStartThreshold = addPositionStartThreshold; return this; }

        public GateConfig build() {
            return new GateConfig(this);