package com.xcong.excoin.modules.gateApi;
import cn.hutool.core.collection.CollUtil;
import io.gate.gateapi.ApiClient;
import io.gate.gateapi.ApiException;
import io.gate.gateapi.GateApiException;
import io.gate.gateapi.api.AccountApi;
import io.gate.gateapi.api.FuturesApi;
import io.gate.gateapi.models.*;
import lombok.extern.slf4j.Slf4j;
import java.io.IOException;
import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import com.xcong.excoin.modules.gateApi.wsHandler.handler.CandlestickChannelHandler;
import com.xcong.excoin.modules.gateApi.wsHandler.handler.PositionClosesChannelHandler;
import com.xcong.excoin.modules.gateApi.wsHandler.handler.PositionsChannelHandler;
/**
* 网格交易策略引擎 — 多空对冲网格。
*
*
策略原理
* 以空仓基底入场价(shortBaseEntryPrice)为价格基准,向上/向下各生成一个价格网格队列。
* 价格触发网格层级时挂条件单,成交后自动挂止盈单。每笔止盈盈利 = step - minTick。
*
* 完整生命周期
*
* init() → startGrid() → WAITING_KLINE
* ↓
* onKline(首根K线) → OPENING → 异步市价双开基底(开多+开空)
* ↓
* onPositionUpdate() → 基底成交 → baseLongOpened && baseShortOpened
* ↓
* tryGenerateQueues()
* ├── generateShortQueue() ← 空仓价格队列(降序,从 shortBaseEntryPrice-step 向下)
* ├── generateLongQueue() ← 多仓价格队列(升序,从 shortBaseEntryPrice+step 向上)
* ├── updateGridElements() ← 构建 GridElement 列表 + TraderParam + 全局索引
* ├── 挂基座止盈单(ID=0 的 long/short takeProfit)
* └── 挂初始条件单(up=-1 多单, down=1 空单)
* ↓
* state = ACTIVE(每根K线反复执行以下循环)
* ↓
* onKline() → processLongGrid() + processShortGrid()
* ├── 匹配队列元素 → 队列补偿 → 保证金检查
* ├── 首元素方向:挂条件开仓单 → 订单ID + GridElement状态同步
* └── 反向守卫:在 downGrid 位置挂对向单(价格区间+trigger方向校验)
* ↓
* onOrderUpdate() ← futures.orders / futures.autoorders 推送
* ├── 匹配止盈单ID → 清空止盈状态(已成交)
* └── 匹配挂单ID → 挂止盈条件单 → 止盈ID + GridElement状态同步
* ↓
* onPositionClose() → cumulativePnl 累加
* ├── ≥ overallTp → STOPPED
* └── ≤ -maxLoss → STOPPED
*
*
* 仓位线动态调整
*
* onPositionUpdate() 中仓位均价变化后:
* longEntryPrice ↑ → 取消 高于 longEntryPrice 的空仓挂单(避免逆势空单)
* shortEntryPrice ↓ → 取消 低于 shortEntryPrice 的多仓挂单(避免逆势多单)
*
*
* 关键公式
*
* step = shortBaseEntryPrice × gridRate ← 网格绝对步长
* minTick = 10^(-priceScale) ← 交易所最小价格单位
* 多止盈 = gridPrice + (step - minTick) ← 多仓止盈价
* 空止盈 = gridPrice - (step - minTick) ← 空仓止盈价
* 单笔盈利 = (step - minTick) × contractMultiplier × quantity ← USDT
*
*
* 线程模型
* 所有 WS 回调(onKline/onPositionUpdate/onOrderUpdate 等)在 WS 回调线程中串行执行。
* 下单/撤单操作提交到 GateTradeExecutor 的单线程池异步执行,避免阻塞 WS 线程。
* stopGrid() 会将 state 设为 STOPPED,后续所有 WS 回调直接返回不再处理。
*
* @author Administrator
*/
@Slf4j
public class GateGridTradeService {
public enum StrategyState {
WAITING_KLINE, OPENING, ACTIVE, STOPPED
}
/**
* 止盈条件单 order_type:仓位计划止盈止损 — 平多仓(支持部分平仓,size<0)。
* 注意:不能用 close-long-position(仅支持全平且双仓需 auto_size),
* 必须用 plan-close-long-position 以支持指定张数部分平仓。
*/
private static final String ORDER_TYPE_CLOSE_LONG = "plan-close-long-position";
/**
* 止盈条件单 order_type:仓位计划止盈止损 — 平空仓(支持部分平仓,size>0)。
* 注意:不能用 close-short-position(仅支持全平且双仓需 auto_size),
* 必须用 plan-close-short-position 以支持指定张数部分平仓。
*/
private static final String ORDER_TYPE_CLOSE_SHORT = "plan-close-short-position";
private final GateConfig config;
private final GateTradeExecutor executor;
private final FuturesApi futuresApi;
private static final String SETTLE = "usdt";
private volatile StrategyState state = StrategyState.WAITING_KLINE;
/** 空仓价格队列,降序排列(大→小),容量 gridQueueSize */
private final List shortPriceQueue = Collections.synchronizedList(new ArrayList<>());
/** 多仓价格队列,升序排列(小→大),容量 gridQueueSize */
private final List longPriceQueue = Collections.synchronizedList(new ArrayList<>());
/** 当前多仓条件单映射:订单ID → 止盈价格,订单成交后通过订单订阅推送匹配止盈 */
private final Map currentLongOrderIds = Collections.synchronizedMap(new LinkedHashMap<>());
/** 当前空仓条件单映射:订单ID → 止盈价格,订单成交后通过订单订阅推送匹配止盈 */
private final Map currentShortOrderIds = Collections.synchronizedMap(new LinkedHashMap<>());
/** 基底空头入场价 */
private BigDecimal shortBaseEntryPrice;
/** 基底多头入场价(仅记录,当前未被业务逻辑消费,保留以备后续使用) */
private BigDecimal longBaseEntryPrice;
/** 基底多头是否已开 */
private volatile boolean baseLongOpened = false;
/** 基底空头是否已开 */
private volatile boolean baseShortOpened = false;
/** 空头是否活跃(有仓位) */
private volatile boolean shortActive = false;
/** 多头是否活跃(有仓位) */
private volatile boolean longActive = false;
private volatile BigDecimal lastKlinePrice;
private volatile BigDecimal markPrice = BigDecimal.ZERO;
private volatile BigDecimal cumulativePnl = BigDecimal.ZERO;
private volatile BigDecimal unrealizedPnl = BigDecimal.ZERO;
private volatile BigDecimal longEntryPrice = BigDecimal.ZERO;
private volatile BigDecimal shortEntryPrice = BigDecimal.ZERO;
private volatile BigDecimal longPositionSize = BigDecimal.ZERO;
private volatile BigDecimal shortPositionSize = BigDecimal.ZERO;
private Long userId;
private volatile BigDecimal initialPrincipal = BigDecimal.ZERO;
public GateGridTradeService(GateConfig config) {
this.config = config;
ApiClient apiClient = new ApiClient();
apiClient.setBasePath(config.getRestBasePath());
apiClient.setApiKeySecret(config.getApiKey(), config.getApiSecret());
this.futuresApi = new FuturesApi(apiClient);
this.executor = new GateTradeExecutor(apiClient, config.getContract());
}
// ---- 初始化 ----
/**
* 初始化策略环境。
*
* 执行顺序
*
* - 获取用户 ID(用于私有频道订阅 payload)
* - 获取账户信息 → 记录初始本金
* - 如需要,切换为双向持仓模式
* - 如需要,调整持仓模式(single/dual)
* - 清除旧的止盈止损条件单
* - 平掉所有已有仓位
* - 设置杠杆倍数
*
*/
public void init() {
try {
ApiClient detailClient = new ApiClient();
detailClient.setBasePath(config.getRestBasePath());
detailClient.setApiKeySecret(config.getApiKey(), config.getApiSecret());
AccountDetail detail = new AccountApi(detailClient).getAccountDetail();
this.userId = detail.getUserId();
log.info("[Gate] 用户ID: {}", userId);
FuturesAccount account = futuresApi.listFuturesAccounts(SETTLE);
this.initialPrincipal = new BigDecimal(account.getTotal());
log.info("[Gate] 初始本金: {} USDT", initialPrincipal);
futuresApi.cancelPriceTriggeredOrderList(SETTLE, config.getContract());
log.info("[Gate] 旧条件单已清除");
closeExistingPositions();
//设置持仓模式为双向持仓
Boolean inDualMode = account.getInDualMode();
if (!inDualMode) {
try {
futuresApi.setDualModeCall(SETTLE,true,null).execute();
} catch (IOException e) {
e.printStackTrace();
}
}
try {
futuresApi.updateDualModePositionLeverageCall(
SETTLE, config.getContract(), config.getLeverage(),
null, null).execute();
} catch (IOException e) {
e.printStackTrace();
}
if (!config.getMarginMode().equals(account.getMarginMode())) {
UpdateDualCompPositionCrossModeRequest updateDualCompPositionCrossModeRequest = new UpdateDualCompPositionCrossModeRequest();
updateDualCompPositionCrossModeRequest.setMode(config.getMarginMode());
updateDualCompPositionCrossModeRequest.setContract(config.getContract());
try {
futuresApi.updateDualCompPositionCrossModeCall(SETTLE, updateDualCompPositionCrossModeRequest, null).execute();
} catch (IOException e) {
e.printStackTrace();
}
}
log.info("[Gate] 持仓模式: {} 余额: {}", config.getPositionMode(), account.getAvailable());
log.info("[Gate] 杠杆: {}x {}", config.getLeverage(), config.getMarginMode());
} catch (GateApiException e) {
log.error("[Gate] 初始化失败, label:{}, msg:{}", e.getErrorLabel(), e.getMessage());
} catch (ApiException e) {
log.error("[Gate] 初始化失败, code:{}", e.getCode());
}
}
/**
* 平掉当前合约的所有已有仓位。
*
* 平仓策略
*
* - 单向持仓:size=相反数,reduceOnly=true,市价 IOC 平仓
* - 双向持仓:size=0,close=false,autoSize=LONG/SHORT,reduceOnly=true,市价 IOC 全平
*
*
* 注意事项
* 双向持仓模式下必须使用 autoSize 参数,不能直接传负数 size,
* 否则 Gate API 会拒绝(双向模式下空头 size 为负是正常的持仓方向)。
*/
private void closeExistingPositions() {
try {
List positions = futuresApi.listPositions(SETTLE).execute();
if (positions == null || positions.isEmpty()) { log.info("[Gate] 无已有仓位"); return; }
for (Position pos : positions) {
if (!config.getContract().equals(pos.getContract())) {
continue;
}
String sizeStr = pos.getSize();
long size = Long.parseLong(sizeStr);
if (size == 0) {
continue;
}
String closeSize = size > 0 ? String.valueOf(-size) : String.valueOf(Math.abs(size));
Position.ModeEnum mode = pos.getMode();
FuturesOrder closeOrder = new FuturesOrder();
closeOrder.setContract(config.getContract());
closeOrder.setPrice("0");
closeOrder.setTif(FuturesOrder.TifEnum.IOC);
closeOrder.setReduceOnly(true);
if (mode != null && mode.getValue() != null && mode.getValue().contains("dual")) {
closeOrder.setSize("0");
closeOrder.setClose(false);
closeOrder.setAutoSize(size > 0 ? FuturesOrder.AutoSizeEnum.LONG : FuturesOrder.AutoSizeEnum.SHORT);
} else {
closeOrder.setSize(closeSize);
}
closeOrder.setText("t-grid-init-close");
futuresApi.createFuturesOrder(SETTLE, closeOrder, null);
log.info("[Gate] 平已有仓位, 方向:{}, size:{}, mode:{}", size > 0 ? "多" : "空", sizeStr, mode);
}
} catch (GateApiException e) {
log.warn("[Gate] 平仓位失败, label:{}, msg:{}", e.getErrorLabel(), e.getMessage());
} catch (Exception e) {
log.warn("[Gate] 平仓位异常", e);
}
}
// ---- 启动/停止 ----
/**
* 启动网格策略。重置所有状态变量和队列,进入 WAITING_KLINE 等待首根 K 线。
* 仅当当前状态为 WAITING_KLINE 或 STOPPED 时才允许启动。
*/
public void startGrid() {
if (state != StrategyState.WAITING_KLINE && state != StrategyState.STOPPED) {
log.warn("[Gate] 策略已在运行中, state:{}", state);
return;
}
state = StrategyState.WAITING_KLINE;
cumulativePnl = BigDecimal.ZERO;
unrealizedPnl = BigDecimal.ZERO;
markPrice = BigDecimal.ZERO;
longEntryPrice = BigDecimal.ZERO;
shortEntryPrice = BigDecimal.ZERO;
longPositionSize = BigDecimal.ZERO;
shortPositionSize = BigDecimal.ZERO;
baseLongOpened = false;
baseShortOpened = false;
longActive = false;
shortActive = false;
shortPriceQueue.clear();
longPriceQueue.clear();
currentLongOrderIds.clear();
currentShortOrderIds.clear();
log.info("[Gate] 网格策略已启动");
}
/**
* 停止网格策略。取消所有条件单 → 关闭交易线程池。
* 状态设为 STOPPED,K 线回调将直接返回不再处理。
*/
public void stopGrid() {
state = StrategyState.STOPPED;
executor.cancelAllPriceTriggeredOrders();
executor.shutdown();
log.info("[Gate] 策略已停止, 累计盈亏: {}", cumulativePnl);
}
// ---- K线回调 ----
/**
* K 线回调入口。由 {@link CandlestickChannelHandler} 在收到 WebSocket K 线推送时调用。
*
* 处理流程
*
* - 更新 lastKlinePrice → 计算 unrealizedPnl(浮动盈亏)
* - STOPPED → 直接返回(仅保留盈亏更新)
* - WAITING_KLINE → 切换为 OPENING → 异步提交基底双开(开多+开空)
* - OPENING → 等待仓位推送回调生成队列,此处返回
* - ACTIVE → 执行 processShortGrid + processLongGrid
*
*
* 注意
* 基底双开下单提交到 GateTradeExecutor 的独立线程池中异步执行,
* 成交状态由 onPositionUpdate 回调驱动,不阻塞 WS 回调线程。
*
* @param closePrice K 线收盘价(即当前最新成交价)
*/
public void onKline(BigDecimal closePrice) {
lastKlinePrice = closePrice;
updateUnrealizedPnl();
if (state == StrategyState.STOPPED) {
return;
}
//初始化0位置的开仓,并且用空的开仓价格,作为价格基准来划分网格
if (state == StrategyState.WAITING_KLINE) {
state = StrategyState.OPENING;
log.info("[Gate] 首根K线到达,开基底仓位...");
executor.openLong(config.getQuantity(), (orderId) -> {
TraderParam baseLongTp = TraderParam.builder()
.entryOrderId(orderId)
.build();
config.setBaseLongTraderParam(baseLongTp);
}, null);
executor.openShort(negate(config.getQuantity()), (orderId) -> {
TraderParam baseShortTp = TraderParam.builder()
.entryOrderId(orderId)
.build();
config.setBaseShortTraderParam(baseShortTp);
}, null);
return;
}
if (state != StrategyState.ACTIVE) {
return;
}
processLongGrid(closePrice);
processShortGrid(closePrice);
}
// ---- 仓位推送回调 ----
/**
* 仓位推送回调。由 {@link PositionsChannelHandler} 在收到 WebSocket 仓位更新时调用。
*
* 处理逻辑
*
* - 有仓位 (size ≠ 0):
*
* - 首次开仓(基底):标记 baseOpened=true,记录基底入场价,双基底都成交后生成网格队列
* - 仓位净减少(size.abs() < 之前记录值):止盈平仓后 → 检查反向条件单条件 →
* 满足时以 entryPrice ± step 为止盈价挂反向市价单(订单ID + 止盈价存入 Map)
* - 仓位净增加或不变:仅更新 positionSize,止盈由 {@link #onOrderUpdate} 通过订单订阅匹配处理
*
*
* - 无仓位 (size = 0):清空活跃标记和持仓量
* - Map 截断:currentLongOrderIds / currentShortOrderIds 超过 5 个时,
* 从 LinkedHashMap 头部删除最旧条目,保留最新 5 个
*
*
* @param contract 合约名称
* @param mode 持仓模式(DUAL_LONG / DUAL_SHORT)
* @param size 持仓张数(多头为正、空头为负)
* @param entryPrice 当前持仓加权均价(交易所计算)
*/
public void onPositionUpdate(String contract, Position.ModeEnum mode, BigDecimal size,
BigDecimal entryPrice) {
if (state == StrategyState.STOPPED || state == StrategyState.WAITING_KLINE) {
return;
}
boolean hasPosition = size.abs().compareTo(BigDecimal.ZERO) > 0;
if (Position.ModeEnum.DUAL_LONG == mode) {
if (hasPosition) {
longActive = true;
longEntryPrice = entryPrice;
if (!baseLongOpened) {
longPositionSize = size;
longBaseEntryPrice = entryPrice;
baseLongOpened = true;
log.info("[Gate] 基底多成交价: {}", longBaseEntryPrice);
tryGenerateQueues();
}else {
longPositionSize = size;
//取消多仓位线以上的开空仓挂单
List allShortOrders = GridElement.findAllShortOrders(longEntryPrice);
if (CollUtil.isNotEmpty(allShortOrders)){
for (GridElement e : allShortOrders) {
executor.cancelOrder(e.getShortOrderId());
}
}
}
} else {
longActive = false;
longPositionSize = BigDecimal.ZERO;
}
} else if (Position.ModeEnum.DUAL_SHORT == mode) {
if (hasPosition) {
shortActive = true;
shortEntryPrice = entryPrice;
if (!baseShortOpened) {
shortPositionSize = size.abs();
shortBaseEntryPrice = entryPrice;
baseShortOpened = true;
log.info("[Gate] 基底空成交价: {}", shortBaseEntryPrice);
tryGenerateQueues();
}else {
shortPositionSize = size.abs();
//取消空仓仓位线以下的开多仓挂单
List allLongOrders = GridElement.findAllLongOrders(shortEntryPrice);
if (CollUtil.isNotEmpty(allLongOrders)){
for (GridElement e : allLongOrders) {
executor.cancelOrder(e.getLongOrderId());
}
}
}
} else {
shortActive = false;
shortPositionSize = BigDecimal.ZERO;
}
}
}
// ---- 平仓推送回调 ----
/**
* 平仓推送回调。由 {@link PositionClosesChannelHandler} 在收到平仓推送时调用。
*
* 累加规则
* cumulativePnl += pnl。止盈平仓时 pnl > 0,止损平仓时 pnl < 0。
* 累加后检查停止条件:≥ overallTp 或 ≤ -maxLoss。
*
* @param contract 合约名称
* @param side 平仓方向("long" / "short")
* @param pnl 本次平仓的盈亏金额
*/
public void onPositionClose(String contract, String side, BigDecimal pnl) {
if (state == StrategyState.STOPPED) {
return;
}
cumulativePnl = cumulativePnl.add(pnl);
log.info("[Gate] 盈亏累加:{}, 方向:{}, 累计:{}", pnl, side, cumulativePnl);
if (cumulativePnl.compareTo(config.getOverallTp()) >= 0) {
log.info("[Gate] 已达止盈目标 {}→已停止", cumulativePnl);
state = StrategyState.STOPPED;
} else if (cumulativePnl.compareTo(config.getMaxLoss().negate()) <= 0) {
log.info("[Gate] 已达亏损上限 {}→已停止", cumulativePnl);
state = StrategyState.STOPPED;
}
}
// ---- 订单推送回调 ----
/**
* 订单推送回调。由 OrdersChannelHandler 在收到订单更新推送时调用。
*
* 处理逻辑
* 当订单状态为 finished 且 finish_as 为 filled 时,
* 从 {@link #currentLongOrderIds} / {@link #currentShortOrderIds} 中匹配订单ID,
* 取出止盈价格并挂止盈单。匹配成功后从 Map 中移除该条目,防止重复挂单。
*
* @param orderId 订单 ID
* @param status 订单状态(open / finished)
* @param finishAs 订单结束方式(filled / cancelled / ioc 等)
*/
public void onOrderUpdate(String orderId, String status, String finishAs) {
if (!"finished".equals(status) || !"filled".equals(finishAs)) {
return;
}
/**
* 匹配止盈单止盈
*/
GridElement byLongTakeProfitOrderId = GridElement.findByLongTakeProfitOrderId(orderId);
if (byLongTakeProfitOrderId != null){
longTakeProfitTraderIdParam(
byLongTakeProfitOrderId,
null,
false
);
longEntryTraderIdParam(
byLongTakeProfitOrderId,
null,
false
);
}
GridElement byShortTakeProfitOrderId = GridElement.findByShortTakeProfitOrderId(orderId);
if (byShortTakeProfitOrderId != null){
shortTakeProfitTraderIdParam(
byShortTakeProfitOrderId,
null,
false
);
shortEntryTraderIdParam(
byShortTakeProfitOrderId,
null,
false
);
}
/**
* 匹配挂单
*/
GridElement longGridElement = GridElement.findByLongOrderId(orderId);
if (longGridElement != null) {
if (longGridElement.isHasLongOrder()){
if (longGridElement.getLongTakeProfitOrderId() == null){
BigDecimal longTp = longGridElement.getLongTraderParam().getTakeProfitPrice();
if (longTp != null) {
executor.placeTakeProfit(longTp,
FuturesPriceTrigger.RuleEnum.NUMBER_1,
ORDER_TYPE_CLOSE_LONG,
negate(config.getQuantity()),
(profitId) -> {
longTakeProfitTraderIdParam(
longGridElement,
profitId,
true
);
});
log.info("[Gate] 多单成交匹配止盈, orderId:{}, 止盈价:{}, size:{}", orderId, longTp, negate(config.getQuantity()));
return;
}
}
}
}
GridElement shortGridElement = GridElement.findByShortOrderId(orderId);
if (shortGridElement != null) {
if (shortGridElement.isHasShortOrder()){
if (shortGridElement.getShortTakeProfitOrderId() == null){
BigDecimal shortTp = shortGridElement.getShortTraderParam().getTakeProfitPrice();
if (shortTp != null) {
executor.placeTakeProfit(shortTp,
FuturesPriceTrigger.RuleEnum.NUMBER_2,
ORDER_TYPE_CLOSE_SHORT,
config.getQuantity(),
(profitId) -> {
shortTakeProfitTraderIdParam(
shortGridElement,
profitId,
true
);
});
log.info("[Gate] 空单成交匹配止盈, orderId:{}, 止盈价:{}, size:{}", orderId, shortTp, config.getQuantity());
}
}
}
}
}
/**
* 用户私有成交回调。由 {@link com.xcong.excoin.modules.gateApi.wsHandler.handler.UserTradesChannelHandler}
* 在收到 {@code futures.usertrades} 推送时调用。
*
* @param contract 合约名称
* @param orderId 订单 ID
* @param price 成交价格
* @param size 成交数量
* @param role 用户角色(maker / taker)
* @param fee 手续费
*/
public void onUserTrade(String contract, String orderId, BigDecimal price, String size, String role, BigDecimal fee) {
if (state == StrategyState.STOPPED) {
return;
}
log.info("[Gate] 成交明细, 合约:{}, 订单ID:{}, 价格:{}, 数量:{}, 角色:{}, 手续费:{}",
contract, orderId, price, size, role, fee);
}
/**
* 自动订单(条件单)状态变更回调。
* 由 {@link com.xcong.excoin.modules.gateApi.wsHandler.handler.AutoOrdersChannelHandler}
* 在收到 {@code futures.autoorders} 推送时调用。
*
* @param orderId 条件单 ID
* @param status 订单状态(open / finished / cancelled)
* @param reason 变更原因
* @param orderType 订单类型(plan-close-long-position 等)
*/
public void onAutoOrder(String orderId, String status, String reason, String orderType) {
if (state == StrategyState.STOPPED) {
return;
}
log.info("[Gate] 条件单状态变更, id:{}, status:{}, reason:{}, order_type:{}",
orderId, status, reason, orderType);
if (!"finished".equals(status)) {
return;
}
/**
* 匹配止盈单止盈
*/
GridElement byLongTakeProfitOrderId = GridElement.findByLongTakeProfitOrderId(orderId);
if (byLongTakeProfitOrderId != null){
longTakeProfitTraderIdParam(
byLongTakeProfitOrderId,
null,
false
);
longEntryTraderIdParam(
byLongTakeProfitOrderId,
null,
false
);
}
GridElement byShortTakeProfitOrderId = GridElement.findByShortTakeProfitOrderId(orderId);
if (byShortTakeProfitOrderId != null){
shortTakeProfitTraderIdParam(
byShortTakeProfitOrderId,
null,
false
);
shortEntryTraderIdParam(
byShortTakeProfitOrderId,
null,
false
);
}
/**
* 匹配挂单
*/
GridElement longGridElement = GridElement.findByLongOrderId(orderId);
if (longGridElement != null) {
if (longGridElement.isHasLongOrder()){
if (longGridElement.getLongTakeProfitOrderId() == null){
BigDecimal longTp = longGridElement.getLongTraderParam().getTakeProfitPrice();
if (longTp != null) {
executor.placeTakeProfit(longTp,
FuturesPriceTrigger.RuleEnum.NUMBER_1,
ORDER_TYPE_CLOSE_LONG,
negate(config.getQuantity()),
(profitId) -> {
longTakeProfitTraderIdParam(
longGridElement,
profitId,
true
);
});
log.info("[Gate] 多单成交匹配止盈, orderId:{}, 止盈价:{}, size:{}", orderId, longTp, negate(config.getQuantity()));
return;
}
}
}
}
GridElement shortGridElement = GridElement.findByShortOrderId(orderId);
if (shortGridElement != null) {
if (shortGridElement.isHasShortOrder()){
if (shortGridElement.getShortTakeProfitOrderId() == null){
BigDecimal shortTp = shortGridElement.getShortTraderParam().getTakeProfitPrice();
if (shortTp != null) {
executor.placeTakeProfit(shortTp,
FuturesPriceTrigger.RuleEnum.NUMBER_2,
ORDER_TYPE_CLOSE_SHORT,
config.getQuantity(),
(profitId) -> {
shortTakeProfitTraderIdParam(
shortGridElement,
profitId,
true
);
});
log.info("[Gate] 空单成交匹配止盈, orderId:{}, 止盈价:{}, size:{}", orderId, shortTp, config.getQuantity());
}
}
}
}
}
// ---- 网格队列处理 ----
/**
* 尝试生成网格队列。双基底(多+空)都成交后才触发:
*
* - 生成空仓价格队列(降序)和多仓价格队列(升序)
* - 挂初始多仓条件单(触发价 = 多仓队列首元素,rule=NUMBER_1 ≥触发价时开多),
* 止盈价 = 触发价 + step,通过 onSuccess 回调将 orderId → 止盈价存入 currentLongOrderIds
* - 挂初始空仓条件单(触发价 = 空仓队列首元素,rule=NUMBER_2 ≤触发价时开空),
* 止盈价 = 触发价 − step,通过 onSuccess 回调将 orderId → 止盈价存入 currentShortOrderIds
* - 状态切换为 ACTIVE
*
* 条件单成交后由 {@link #onOrderUpdate} 匹配止盈价并挂止盈条件单。
*/
private void tryGenerateQueues() {
if (baseLongOpened && baseShortOpened) {
//初始化空仓队列
generateShortQueue();
//初始化多仓队列
generateLongQueue();
//初始化网格数据
updateGridElements();
/**
* 挂初始位置多空仓条件单
* 0位置的多单止盈
* 0位置的空单止盈
*/
GridElement baseGridElement = GridElement.findById(0);
TraderParam baseLongTraderParam = config.getBaseLongTraderParam();
baseGridElement.setLongOrderId(baseLongTraderParam.getEntryOrderId());
baseGridElement.setHasLongOrder(true);
//0位置的网格的多单止盈
BigDecimal upTakeProfitPrice = baseGridElement.getLongTraderParam().getTakeProfitPrice();
executor.placeTakeProfit(
upTakeProfitPrice,
FuturesPriceTrigger.RuleEnum.NUMBER_1,
ORDER_TYPE_CLOSE_LONG,
negate(config.getQuantity()),
profitId -> {
longTakeProfitTraderIdParam(
baseGridElement,
profitId,
true
);
}
);
//0位置的网格的空单止盈
TraderParam baseShortTraderParam = config.getBaseShortTraderParam();
baseGridElement.setShortOrderId(baseShortTraderParam.getEntryOrderId());
baseGridElement.setHasShortOrder(true);
BigDecimal downTakeProfitPrice = baseGridElement.getShortTraderParam().getTakeProfitPrice();
executor.placeTakeProfit(
downTakeProfitPrice,
FuturesPriceTrigger.RuleEnum.NUMBER_2,
ORDER_TYPE_CLOSE_SHORT,
config.getQuantity(),
profitId -> {
shortTakeProfitTraderIdParam(
baseGridElement,
profitId,
true
);
}
);
/**
* 挂初始位置的up位置的多单
* 挂初始位置的down位置的空单
*/
Integer upId = baseGridElement.getUpId();
GridElement upGridElementOne = GridElement.findById(upId);
BigDecimal longTp = upGridElementOne.getGridPrice();
executor.placeConditionalEntryOrder(
longTp,
FuturesPriceTrigger.RuleEnum.NUMBER_1,
config.getQuantity(),
orderId -> {
longEntryTraderIdParam(
upGridElementOne,
orderId,
true
);
},
null);
Integer downId = baseGridElement.getDownId();
GridElement downGridElementOne = GridElement.findById(downId);
BigDecimal shortTp = downGridElementOne.getGridPrice();
executor.placeConditionalEntryOrder(
shortTp,
FuturesPriceTrigger.RuleEnum.NUMBER_2,
negate(config.getQuantity()),
orderId -> {
shortEntryTraderIdParam(
downGridElementOne,
orderId,
true
);
},
null);
state = StrategyState.ACTIVE;
}
}
/**
* 更新基座止盈信息,将止盈价、订单ID等写入 TraderParam 并回填到 ID=0 的网格元素中。
*/
private void longTakeProfitTraderIdParam(
GridElement baseElement,String profitId, boolean flag
) {
TraderParam tp = baseElement.getLongTraderParam();
tp.setTakeProfitOrderId(profitId);
tp.setTakeProfitPlaced(flag);
baseElement.setLongTakeProfitOrderId(profitId);
GridElement.refreshIndices();
}
private void shortTakeProfitTraderIdParam(
GridElement baseElement,String profitId, boolean flag
) {
TraderParam tp = baseElement.getShortTraderParam();
tp.setTakeProfitOrderId(profitId);
tp.setTakeProfitPlaced(flag);
baseElement.setShortTakeProfitOrderId(profitId);
GridElement.refreshIndices();
}
private void longEntryTraderIdParam(
GridElement baseElement,String entryId,boolean flag
) {
TraderParam tp = baseElement.getLongTraderParam();
tp.setEntryOrderId(entryId);
tp.setEntryOrderPlaced(flag);
baseElement.setHasLongOrder(flag);
baseElement.setLongOrderId(entryId);
GridElement.refreshIndices();
}
private void shortEntryTraderIdParam(
GridElement baseElement, String entryId, boolean flag
) {
TraderParam tp = baseElement.getShortTraderParam();
tp.setEntryOrderId(entryId);
tp.setEntryOrderPlaced(flag);
baseElement.setHasShortOrder(flag);
baseElement.setShortOrderId(entryId);
GridElement.refreshIndices();
}
/**
* 生成空仓价格队列。
* 以 shortBaseEntryPrice × gridRate 作为绝对步长 step,存到 config。
* 第1个元素 = shortBaseEntryPrice − step,后续依次递减 step,共 gridQueueSize 个。
* 队列降序排列(大→小),方便 processShortGrid 中从头遍历。
*/
private void generateShortQueue() {
shortPriceQueue.clear();
int prec = config.getPriceScale();
BigDecimal step = shortBaseEntryPrice.multiply(config.getGridRate()).setScale(prec, RoundingMode.HALF_UP);
config.setStep(step);
BigDecimal elem = shortBaseEntryPrice.subtract(step).setScale(prec, RoundingMode.HALF_UP);
for (int i = 0; i < config.getGridQueueSize(); i++) {
shortPriceQueue.add(elem);
elem = elem.subtract(step).setScale(prec, RoundingMode.HALF_UP);
if (elem.compareTo(BigDecimal.ZERO) <= 0) {
break;
}
}
shortPriceQueue.sort((a, b) -> b.compareTo(a));
log.info("[Gate] 空队列:{}", shortPriceQueue);
}
/**
* 生成多仓价格队列。
* 以 shortBaseEntryPrice + step 为首元素,后续依次递增 step,共 gridQueueSize 个。
* 队列升序排列(小→大),方便 processLongGrid 中从头遍历。
*/
private void generateLongQueue() {
longPriceQueue.clear();
int prec = config.getPriceScale();
BigDecimal step = config.getStep();
BigDecimal elem = shortBaseEntryPrice.add(step).setScale(prec, RoundingMode.HALF_UP);
for (int i = 0; i < config.getGridQueueSize(); i++) {
longPriceQueue.add(elem);
elem = elem.add(step).setScale(prec, RoundingMode.HALF_UP);
}
longPriceQueue.sort(BigDecimal::compareTo);
log.info("[Gate] 多队列:{}", longPriceQueue);
}
/**
* 根据当前多空价格队列同步构建网格元素列表,写入 config。
*
* ID 分配规则
*
* - 空仓队列:id 从 -1 自减(-1, -2, -3...),第一个元素 upId=0,最后一个 downId=null
* - 位置 0:gridPrice=shortBaseEntryPrice,upId=-1,downId=1,其数据在基座开仓时更新
* - 多仓队列:id 从 1 自增(1, 2, 3...),第一个元素 upId=0,最后一个 downId=null
*
*
* 链表关系
* 所有元素通过 upId/downId 串成一条双向链表:
* ... → -3 → -2 → -1 → 0 → 1 → 2 → 3 → ...
*/
private void updateGridElements() {
List elements = new ArrayList<>();
int shortSize = shortPriceQueue.size();
int longSize = longPriceQueue.size();
//根据精度转换成小数
int prec = config.getPriceScale();
BigDecimal minTick = BigDecimal.ONE.scaleByPowerOfTen(-prec);
BigDecimal step = config.getStep().subtract(minTick);
String qty = config.getQuantity();
// 空仓队列:id 从 -1 自减, shortPriceQueue[i] → id=-(i+1)
for (int i = 0; i < shortSize; i++) {
int id = -(i + 1);
Integer upId = (i == 0) ? 0 : id + 1;
Integer downId = (i == shortSize - 1) ? null : id - 1;
BigDecimal price = shortPriceQueue.get(i);
TraderParam longParam = TraderParam.builder()
.direction(TraderParam.Direction.LONG)
.entryPrice(price)
.takeProfitPrice(price.add(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
TraderParam shortParam = TraderParam.builder()
.direction(TraderParam.Direction.SHORT)
.entryPrice(price)
.takeProfitPrice(price.subtract(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
elements.add(GridElement.builder()
.id(id)
.gridPrice(price)
.upId(upId)
.downId(downId)
.longTraderParam(longParam)
.shortTraderParam(shortParam)
.build());
}
// 位置 0:基底价格,数据在基座开仓时更新
{
BigDecimal price = shortBaseEntryPrice;
TraderParam longParam = TraderParam.builder()
.direction(TraderParam.Direction.LONG)
.entryPrice(price)
.takeProfitPrice(price.add(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
TraderParam shortParam = TraderParam.builder()
.direction(TraderParam.Direction.SHORT)
.entryPrice(price)
.takeProfitPrice(price.subtract(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
elements.add(GridElement.builder()
.id(0)
.gridPrice(price)
.upId(shortSize > 0 ? 1 : null)
.downId(longSize > 0 ? -1 : null)
.longTraderParam(longParam)
.shortTraderParam(shortParam)
.build());
}
// 多仓队列:id 从 1 自增, longPriceQueue[i] → id=i+1
for (int i = 0; i < longSize; i++) {
int id = i + 1;
Integer downId = (i == 0) ? 0 : id - 1;
Integer upId = (i == longSize - 1) ? null : id + 1;
BigDecimal price = longPriceQueue.get(i);
TraderParam longParam = TraderParam.builder()
.direction(TraderParam.Direction.LONG)
.entryPrice(price)
.takeProfitPrice(price.add(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
TraderParam shortParam = TraderParam.builder()
.direction(TraderParam.Direction.SHORT)
.entryPrice(price)
.takeProfitPrice(price.subtract(step).setScale(prec, RoundingMode.HALF_UP))
.quantity(qty)
.build();
elements.add(GridElement.builder()
.id(id)
.gridPrice(price)
.upId(upId)
.downId(downId)
.longTraderParam(longParam)
.shortTraderParam(shortParam)
.build());
}
config.setGridElements(elements);
log.info("[Gate] 网格元素列表已构建, 共{}个元素 (空仓:{} 位置:0 多仓:{})", elements.size(), shortSize, longSize);
}
private void processShortGrid(BigDecimal currentPrice) {
int prec = config.getPriceScale();
List matched = new ArrayList<>();
synchronized (shortPriceQueue) {
for (BigDecimal p : shortPriceQueue) {
if (p.compareTo(currentPrice) >= 0) {
matched.add(p);
} else {
break;
}
}
}
if (matched.isEmpty()) {
return;
}
log.info("[Gate] 空仓队列触发, 匹配{}个元素, 当前价:{}", matched.size(), currentPrice);
synchronized (shortPriceQueue) {
shortPriceQueue.removeAll(matched);
BigDecimal min = shortPriceQueue.isEmpty() ? matched.get(matched.size() - 1) : shortPriceQueue.get(shortPriceQueue.size() - 1);
BigDecimal gridStep = config.getStep();
for (int i = 0; i < matched.size(); i++) {
min = min.subtract(gridStep).setScale(prec, RoundingMode.HALF_UP);
shortPriceQueue.add(min);
}
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(prec, 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] 保证金超限,跳过挂条件单");
} else {
/**
* 下一个开仓位置
* 获取队列第一个元素的价格对应的网格
* 判断网格是否能开空仓,如果不能则跳过
* 前进方向挂空仓条件单
* 后置方向挂多空条件单
*/
//下一个开仓位置
BigDecimal newLongFirst = shortPriceQueue.get(0);
GridElement UpGridElement = GridElement.findByPrice(newLongFirst);
// 判断网格是否能开空仓,如果不能则跳过
if (UpGridElement != null) {
if (!UpGridElement.isHasShortOrder()) {
//挂空仓条件单
TraderParam upShortTraderParam = UpGridElement.getShortTraderParam();
executor.placeConditionalEntryOrder(
upShortTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_2,
negate(upShortTraderParam.getQuantity()),
orderId ->
{
shortEntryTraderIdParam(
UpGridElement,
orderId,
true
);
},
null
);
}
int i = UpGridElement.getId() + 2;
GridElement downGridElement = GridElement.findById(i);
if (downGridElement != null){
BigDecimal downGridPrice = downGridElement.getGridPrice();
TraderParam downShortTraderParam = downGridElement.getShortTraderParam();
if (
!downGridElement.isHasShortOrder() &&
downGridPrice.compareTo(longEntryPrice) <= 0 &&
downGridPrice.compareTo(shortEntryPrice) >= 0
){
executor.placeConditionalEntryOrder(
downShortTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_2,
negate(downShortTraderParam.getQuantity()),
orderId ->
{
shortEntryTraderIdParam(
downGridElement,
orderId,
true
);
},
null
);
}
TraderParam downLongTraderParam = downGridElement.getLongTraderParam();
if (
!downGridElement.isHasLongOrder() &&
downGridPrice.compareTo(longEntryPrice) <= 0
){
executor.placeConditionalEntryOrder(
downLongTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_1,
downLongTraderParam.getQuantity(),
orderId ->
{
longEntryTraderIdParam(
downGridElement,
orderId,
true
);
},
null
);
}
}
}
}
}
private void processLongGrid(BigDecimal currentPrice) {
int prec = config.getPriceScale();
List matched = new ArrayList<>();
synchronized (longPriceQueue) {
for (BigDecimal p : longPriceQueue) {
if (p.compareTo(currentPrice) <= 0) {
matched.add(p);
} else {
break;
}
}
}
if (matched.isEmpty()) {
return;
}
log.info("[Gate] 多仓队列触发, 匹配{}个元素, 当前价:{}", matched.size(), currentPrice);
/**
* 匹配到元素后,
* 多仓队列更新
* 空仓队列更新
*/
synchronized (longPriceQueue) {
longPriceQueue.removeAll(matched);
BigDecimal max = longPriceQueue.isEmpty() ? matched.get(matched.size() - 1) : longPriceQueue.get(longPriceQueue.size() - 1);
BigDecimal gridStep = config.getStep();
for (int i = 0; i < matched.size(); i++) {
max = max.add(gridStep).setScale(prec, RoundingMode.HALF_UP);
longPriceQueue.add(max);
}
longPriceQueue.sort(BigDecimal::compareTo);
}
synchronized (shortPriceQueue) {
BigDecimal first = shortPriceQueue.isEmpty() ? matched.get(0) : shortPriceQueue.get(0);
BigDecimal gridStep = config.getStep();
for (int i = 1; i <= matched.size(); i++) {
BigDecimal elem = first.add(gridStep.multiply(BigDecimal.valueOf(i))).setScale(prec, RoundingMode.HALF_UP);
shortPriceQueue.add(elem);
}
shortPriceQueue.sort((a, b) -> b.compareTo(a));
while (shortPriceQueue.size() > config.getGridQueueSize()) {
shortPriceQueue.remove(shortPriceQueue.size() - 1);
}
}
if (!isMarginSafe()) {
log.warn("[Gate] 保证金超限,跳过挂条件单");
} else {
/**
* 下一个开仓位置
* 获取队列第一个元素的价格对应的网格
* 判断网格是否能开多仓,如果不能则跳过
* 前进方向挂多仓条件单
* 后置方向挂多空条件单
*/
//下一个开仓位置
BigDecimal newLongFirst = longPriceQueue.get(0);
GridElement UpGridElement = GridElement.findByPrice(newLongFirst);
// 判断网格是否能开多仓,如果不能则跳过
if (UpGridElement != null) {
if (!UpGridElement.isHasLongOrder()) {
//挂多仓条件单
TraderParam upLongTraderParam = UpGridElement.getLongTraderParam();
executor.placeConditionalEntryOrder(
upLongTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_1,
config.getQuantity(),
orderId ->
{
longEntryTraderIdParam(
UpGridElement,
orderId,
true
);
},
null
);
}
int i = UpGridElement.getId() - 2;
GridElement downGridElement = GridElement.findById(i);
if (downGridElement != null){
BigDecimal downGridPrice = downGridElement.getGridPrice();
TraderParam downLongTraderParam = downGridElement.getLongTraderParam();
if (
!downGridElement.isHasLongOrder() &&
downGridPrice.compareTo(shortEntryPrice) >= 0 &&
downGridPrice.compareTo(longEntryPrice) <= 0
){
executor.placeConditionalEntryOrder(
downLongTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_1,
config.getQuantity(),
orderId ->
{
longEntryTraderIdParam(
downGridElement,
orderId,
true
);
},
null
);
}
TraderParam shortTraderParam = downGridElement.getShortTraderParam();
if (
!downGridElement.isHasShortOrder() &&
downGridPrice.compareTo(shortEntryPrice) >= 0
){
executor.placeConditionalEntryOrder(
shortTraderParam.getEntryPrice(),
FuturesPriceTrigger.RuleEnum.NUMBER_2,
negate(config.getQuantity()),
orderId ->
{
shortEntryTraderIdParam(
downGridElement,
orderId,
true
);
},
null
);
}
}
}
}
}
// ---- 保证金安全阀 ----
/**
* 保证金安全阀检查。
*
* 实时查询当前保证金占用额(positionInitialMargin),计算其占初始本金的比例。
* 比例 ≥ marginRatioLimit(默认 20%)时拒绝开仓,但仍照常更新队列。
*
*
查询失败时默认放行(返回 true),避免因 REST API 异常导致策略完全停滞。
*
* @return true=安全可开仓 / false=保证金超限跳过开仓
*/
private boolean isMarginSafe() {
try {
FuturesAccount account = futuresApi.listFuturesAccounts(SETTLE);
BigDecimal margin = new BigDecimal(account.getPositionInitialMargin());
BigDecimal ratio = margin.divide(initialPrincipal, 4, RoundingMode.HALF_UP);
log.debug("[Gate] 保证金比例: {}/{}={}", margin, initialPrincipal, ratio);
return ratio.compareTo(config.getMarginRatioLimit()) < 0;
} catch (Exception e) {
log.warn("[Gate] 查保证金失败,默认放行", e);
return true;
}
}
// ---- 工具 ----
/**
* 取反字符串数字。如 "1" → "-1","-2" → "2"。
* 用于开空单时将正数张数转为负数。
*/
private String negate(String qty) {
return qty.startsWith("-") ? qty.substring(1) : "-" + qty;
}
/**
* 根据持仓和当前价格计算未实现盈亏。
*
*
正向合约公式
*
* 多仓: 持仓量 × 合约乘数 × (计价价格 − 开仓均价)
* 空仓: 持仓量 × 合约乘数 × (开仓均价 − 计价价格)
*
* 计价价格由 {@link GateConfig.PnLPriceMode} 决定:LAST_PRICE 用最新成交价,MARK_PRICE 用标记价格。
*/
private void updateUnrealizedPnl() {
BigDecimal price = resolvePnlPrice();
if (price == null || price.compareTo(BigDecimal.ZERO) == 0) {
return;
}
BigDecimal multiplier = config.getContractMultiplier();
BigDecimal longPnl = BigDecimal.ZERO;
BigDecimal shortPnl = BigDecimal.ZERO;
if (longPositionSize.compareTo(BigDecimal.ZERO) > 0 && longEntryPrice.compareTo(BigDecimal.ZERO) > 0) {
longPnl = longPositionSize.multiply(multiplier).multiply(price.subtract(longEntryPrice));
}
if (shortPositionSize.compareTo(BigDecimal.ZERO) > 0 && shortEntryPrice.compareTo(BigDecimal.ZERO) > 0) {
shortPnl = shortPositionSize.multiply(multiplier).multiply(shortEntryPrice.subtract(price));
}
unrealizedPnl = longPnl.add(shortPnl);
log.info("[Gate] 未实现盈亏: {}", unrealizedPnl);
}
/**
* 根据配置的 PnLPriceMode 返回计价价格。
* MARK_PRICE 模式优先使用标记价格(外部注入),未注入时回退到最新成交价。
*
* @return 计价价格,可能为 null
*/
private BigDecimal resolvePnlPrice() {
if (config.getUnrealizedPnlPriceMode() == GateConfig.PnLPriceMode.MARK_PRICE
&& markPrice.compareTo(BigDecimal.ZERO) > 0) {
return markPrice;
}
return lastKlinePrice;
}
/** @return 最新 K 线价格(每次 onKline 更新) */
public BigDecimal getLastKlinePrice() { return lastKlinePrice; }
/** 设置标记价格(外部注入,MARK_PRICE 模式时用于盈亏计算) */
public void setMarkPrice(BigDecimal markPrice) { this.markPrice = markPrice; }
/** @return 策略是否处于活跃状态(非 STOPPED 且非 WAITING_KLINE) */
public boolean isStrategyActive() { return state != StrategyState.STOPPED && state != StrategyState.WAITING_KLINE; }
/** @return 累计已实现盈亏(平仓推送驱动累加) */
public BigDecimal getCumulativePnl() { return cumulativePnl; }
/** @return 当前未实现盈亏(每根 K 线实时计算) */
public BigDecimal getUnrealizedPnl() { return unrealizedPnl; }
/** @return Gate 用户 ID(用于私有频道订阅 payload) */
public Long getUserId() { return userId; }
/** @return 当前策略状态 */
public StrategyState getState() { return state; }
}