From a986f3571c7e18ade4665fe5999b445b5762264d Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Mon, 11 May 2026 23:07:15 +0800
Subject: [PATCH] refactor(gateApi): 修改网格交易队列生成算法

---
 src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java |   45 +++++++++++++++++++++++++++++++++++++++++----
 1 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java b/src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java
index f3173d2..8fb1d08 100644
--- a/src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java
+++ b/src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java
@@ -52,12 +52,24 @@
         this.gridTradeService = gridTradeService;
     }
 
+    /** @return 频道名称（如 "futures.positions"） */
     @Override
     public String getChannelName() { return channelName; }
 
     /**
      * 发送带签名的订阅请求。
-     * payload: [userId, contract]，auth: {method:"api_key", KEY, SIGN}
+     *
+     * <h3>请求格式</h3>
+     * <pre>
+     * {
+     *   "id":     &lt;唯一请求ID&gt;,
+     *   "time":   &lt;unix时间戳(秒)&gt;,
+     *   "channel":"futures.positions",
+     *   "event":  "subscribe",
+     *   "payload":[userId, contract],
+     *   "auth":   {"method":"api_key", "KEY":&lt;APIKEY&gt;, "SIGN":&lt;HMAC-SHA512签名&gt;}
+     * }
+     * </pre>
      */
     @Override
     public void subscribe(WebSocketClient ws) {
@@ -68,7 +80,8 @@
     }
 
     /**
-     * 发送带签名的取消订阅请求，与 subscribe 对称。
+     * 发送带签名的取消订阅请求，与 subscribe 结构一致。
+     * payload: [contract]，无 userId（取消订阅不需要用户ID）。
      */
     @Override
     public void unsubscribe(WebSocketClient ws) {
@@ -90,11 +103,15 @@
         log.info("[{}] 取消订阅成功, 合约:{}", channelName, contract);
     }
 
+    /** @return 网格交易服务实例 */
     protected GateGridTradeService getGridTradeService() { return gridTradeService; }
+    /** @return 当前订阅的合约名称 */
     protected String getContract() { return contract; }
 
     /**
      * 从策略服务获取用户 ID，用于私有频道订阅的 payload[0]。
+     *
+     * @return 用户 ID 字符串，获取失败返回空字符串
      */
     private String buildUid() {
         return gridTradeService != null && gridTradeService.getUserId() != null
@@ -102,7 +119,13 @@
     }
 
     /**
-     * 构建认证请求 JSON。包含 id、time、channel、event、payload[auth_user_id, contract]、auth 字段。
+     * 构建认证请求 JSON。
+     * 包含 id、time、channel、event、payload[userId, contract]、auth 字段。
+     *
+     * @param event   事件类型（"subscribe" / "unsubscribe"）
+     * @param uid     认证用户 ID
+     * @param timeSec unix 时间戳（秒）
+     * @return 完整的认证请求 JSONObject
      */
     private JSONObject buildAuthRequest(String event, String uid, long timeSec) {
         JSONObject msg = new JSONObject();
@@ -123,7 +146,21 @@
     }
 
     /**
-     * HMAC-SHA512 签名，使用 UTF-8 编码。
+     * HMAC-SHA512 签名计算。
+     *
+     * <h3>签名算法</h3>
+     * <pre>
+     *   message = "channel={channelName}&event={event}&time={timeSec}"
+     *   SIGN = Hex(HmacSHA512(apiSecret(UTF-8), message(UTF-8)))
+     * </pre>
+     *
+     * <h3>错误处理</h3>
+     * 签名计算失败时返回空字符串（日志记录错误），不抛异常，
+     * 避免阻塞 WebSocket 回调线程。
+     *
+     * @param event   事件类型
+     * @param timeSec unix 时间戳（秒）
+     * @return 十六进制签名字符串，失败返回 ""
      */
     private String hs512Sign(String event, long timeSec) {
         try {

--
Gitblit v1.9.1