feat(gateApi): 更新网格交易逻辑文档和实现

Administrator

9 hours ago 0d9c31cc7be76229cf71e141444598992758ebf6

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

@@ -14,6 +14,7 @@
import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
import java.util.function.Consumer;

/**
 * Gate REST API 执行器。
@@ -209,6 +210,128 @@
    }

    /**
     * 异步挂限价单（GTC），用于网格限价开仓。
     *
     * @param price     限价价格
     * @param size      下单张数（正=多 / 负=空）
     * @param onSuccess 成功回调，接收 orderId（可为 null）
     * @param onFailure 失败回调（可为 null）
     */
    public void placeGridLimitOrder(BigDecimal price, String size, Consumer<String> onSuccess, Runnable onFailure) {
        executor.execute(() -> {
            try {
                FuturesOrder order = new FuturesOrder();
                order.setContract(contract);
                order.setSize(size);
                order.setPrice(price.toString());
                order.setTif(FuturesOrder.TifEnum.GTC);
                order.setText(size.startsWith("-") ? "t-grid-limit-short" : "t-grid-limit-long");
                FuturesOrder result = futuresApi.createFuturesOrder(SETTLE, order, null);
                log.info("[TradeExec] 限价单已挂, price:{}, size:{}, id:{}, status:{}", price, size, result.getId(), result.getStatus());
                if (onSuccess != null) {
                    onSuccess.accept(String.valueOf(result.getId()));
                }
            } catch (Exception e) {
                log.error("[TradeExec] 限价单挂单失败, price:{}, size:{}", price, size, e);
                if (onFailure != null) {
                    onFailure.run();
                }
            }
        });
    }

    /**
     * 异步取消指定订单。
     *
     * @param orderId 订单 ID，为 null 时跳过
     */
    public void cancelOrder(String orderId) {
        if (orderId == null) {
            return;
        }
        executor.execute(() -> {
            try {
                FuturesOrder cancelled = futuresApi.cancelFuturesOrder(SETTLE, orderId, null);
                log.info("[TradeExec] 订单已取消, id:{}, status:{}", orderId, cancelled.getStatus());
            } catch (Exception e) {
                log.warn("[TradeExec] 取消订单失败(可能已成交), id:{}", orderId);
            }
        });
    }

    /**
     * 异步创建条件开仓单（价格触发开仓）。
     *
     * <p>服务器监控价格，达到触发价后以市价 IOC 开仓。与止盈单不同，不设 order_type（默认开仓），
     * reduce_only=false。适用于"价格到达 X 才买入 / 跌到 Y 才卖出"的场景。
     *
     * @param triggerPrice 触发价格
     * @param rule         触发规则（NUMBER_1: 最新价≥触发价时执行；NUMBER_2: 最新价≤触发价时执行）
     * @param size         开仓张数（正=开多，负=开空）
     * @param onSuccess    成功回调，接收 conditionOrderId
     * @param onFailure    失败回调
     */
    public void placeConditionalEntryOrder(BigDecimal triggerPrice,
                                            FuturesPriceTrigger.RuleEnum rule,
                                            String size,
                                            Consumer<String> onSuccess,
                                            Runnable onFailure) {
        executor.execute(() -> {
            try {
                FuturesPriceTrigger trigger = new FuturesPriceTrigger();
                trigger.setStrategyType(FuturesPriceTrigger.StrategyTypeEnum.NUMBER_0);
                trigger.setPriceType(FuturesPriceTrigger.PriceTypeEnum.NUMBER_0);
                trigger.setPrice(triggerPrice.toString());
                trigger.setRule(rule);
                trigger.setExpiration(0);

                FuturesInitialOrder initial = new FuturesInitialOrder();
                initial.setContract(contract);
                initial.setSize(Long.parseLong(size));
                initial.setPrice("0");
                initial.setTif(FuturesInitialOrder.TifEnum.IOC);
                initial.setReduceOnly(false);

                FuturesPriceTriggeredOrder order = new FuturesPriceTriggeredOrder();
                order.setTrigger(trigger);
                order.setInitial(initial);

                TriggerOrderResponse response = futuresApi.createPriceTriggeredOrder(SETTLE, order);
                String orderId = String.valueOf(response.getId());
                log.info("[TradeExec] 条件开仓单已创建, trigger:{}, rule:{}, size:{}, id:{}",
                        triggerPrice, rule, size, orderId);
                if (onSuccess != null) {
                    onSuccess.accept(orderId);
                }
            } catch (Exception e) {
                log.error("[TradeExec] 条件开仓单创建失败, trigger:{}, size:{}", triggerPrice, size, e);
                if (onFailure != null) {
                    onFailure.run();
                }
            }
        });
    }

    /**
     * 异步取消单个条件单。
     *
     * @param orderId 条件单 ID，为 null 时跳过
     */
    public void cancelConditionalOrder(String orderId) {
        if (orderId == null) {
            return;
        }
        executor.execute(() -> {
            try {
                futuresApi.cancelPriceTriggeredOrder(SETTLE, Long.parseLong(orderId));
                log.info("[TradeExec] 条件单已取消, id:{}", orderId);
            } catch (Exception e) {
                log.warn("[TradeExec] 取消条件单失败(可能已触发), id:{}", orderId);
            }
        });
    }

    /**
     * 构建 FuturesPriceTriggeredOrder 对象。
     *
     * <p>策略=0（价格触发），price_type=0（最新价），expiration=0（永不过期），