From 5d884f3ba7340d34891a5e50d2e8b7fa83c84c73 Mon Sep 17 00:00:00 2001
From: Administrator <15274802129@163.com>
Date: Mon, 11 May 2026 14:11:18 +0800
Subject: [PATCH] docs(gateApi): 更新代码注释和文档说明

---
 src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/AbstractPrivateChannelHandler.java |   51 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 44 insertions(+), 7 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 9c51b45..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,23 +52,36 @@
         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) {
         long timeSec = System.currentTimeMillis() / 1000;
         JSONObject msg = buildAuthRequest("subscribe", buildUid(), timeSec);
         ws.send(msg.toJSONString());
-        log.info("[{}] subscribed, contract:{}", channelName, contract);
+        log.info("[{}] 订阅成功, 合约:{}", channelName, contract);
     }
 
     /**
-     * 发送带签名的取消订阅请求，与 subscribe 对称。
+     * 发送带签名的取消订阅请求，与 subscribe 结构一致。
+     * payload: [contract]，无 userId（取消订阅不需要用户ID）。
      */
     @Override
     public void unsubscribe(WebSocketClient ws) {
@@ -87,14 +100,18 @@
         auth.put("SIGN", hs512Sign("unsubscribe", timeSec));
         msg.put("auth", auth);
         ws.send(msg.toJSONString());
-        log.info("[{}] unsubscribed, contract:{}", channelName, contract);
+        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 {
@@ -139,7 +176,7 @@
             }
             return hex.toString();
         } catch (Exception e) {
-            log.error("[{}] sign fail", channelName, e);
+            log.error("[{}] 签名计算失败", channelName, e);
             return "";
         }
     }

--
Gitblit v1.9.1