docs(gateApi): 更新代码注释和文档说明

Administrator

yesterday 5d884f3ba7340d34891a5e50d2e8b7fa83c84c73

 src/main/java/com/xcong/excoin/modules/gateApi/wsHandler/handler/CandlestickChannelHandler.java

@@ -20,8 +20,8 @@
 * <pre>
 *   WebSocket 推送 update event
 *     → handleMessage() → 解析 OHLCV → log 打印 → gridTradeService.onKline(closePx)
 *       → 首次 K 线触发双开
 *       → 后续 K 线仅缓存 lastKlinePrice 供补仓参考
 *       → WAITING_KLINE: 首次 K 线触发基底双开
 *       → ACTIVE: 驱动 processShortGrid + processLongGrid 网格触发
 * </pre>
 *
 * <h3>订阅格式</h3>
@@ -43,9 +43,23 @@
        this.gridTradeService = gridTradeService;
    }

    /** @return 频道名称 "futures.candlesticks" */
    @Override
    public String getChannelName() { return CHANNEL_NAME; }

    /**
     * 发送 K 线频道订阅请求（公开频道，无需签名）。
     *
     * <h3>订阅格式</h3>
     * <pre>
     * {
     *   "time":    &lt;unix时间戳(秒)&gt;,
     *   "channel": "futures.candlesticks",
     *   "event":   "subscribe",
     *   "payload": ["1m", "{contract}"]
     * }
     * </pre>
     */
    @Override
    public void subscribe(WebSocketClient ws) {
        JSONObject msg = new JSONObject();
@@ -57,9 +71,12 @@
        payload.add(contract);
        msg.put("payload", payload);
        ws.send(msg.toJSONString());
        log.info("[{}] subscribed, contract:{}, interval:{}", CHANNEL_NAME, contract, INTERVAL);
        log.info("[{}] 订阅成功, 合约:{}, 周期:{}", CHANNEL_NAME, contract, INTERVAL);
    }

    /**
     * 发送 K 线频道取消订阅请求。
     */
    @Override
    public void unsubscribe(WebSocketClient ws) {
        JSONObject msg = new JSONObject();
@@ -71,28 +88,48 @@
        payload.add(contract);
        msg.put("payload", payload);
        ws.send(msg.toJSONString());
        log.info("[{}] unsubscribed", CHANNEL_NAME);
        log.info("[{}] 取消订阅成功", CHANNEL_NAME);
    }

    /**
     * 处理 K 线推送消息。
     *
     * <h3>数据提取</h3>
     * result[0] 中提取：
     * <ul>
     *   <li>c（close）：收盘价 → 传给 gridTradeService.onKline()</li>
     *   <li>n（name）：烛线名称（如 "1m_ETH_USDT"）</li>
     *   <li>t（time）：烛线起始时间戳</li>
     *   <li>w（window_close）：烛线是否完结（仅日志输出，不做门控）</li>
     * </ul>
     *
     * <h3>注意</h3>
     * 不判断 w（已完结）——策略需要 tick 级实时响应价格变动，
     * 而非等 1 分钟烛线完结后才行动。
     *
     * @param response WebSocket 推送的完整 JSON
     * @return true 表示已处理（匹配成功）
     */
    @Override
    public boolean handleMessage(JSONObject response) {
        if (!CHANNEL_NAME.equals(response.getString("channel"))) return false;
        if (!CHANNEL_NAME.equals(response.getString("channel"))) {
            return false;
        }
        try {
            JSONArray resultArray = response.getJSONArray("result");
            if (resultArray == null || resultArray.isEmpty()) { log.warn("[{}] empty", CHANNEL_NAME); return true; }
            if (resultArray == null || resultArray.isEmpty()) { log.warn("[{}] 数据为空", CHANNEL_NAME); return true; }
            JSONObject data = resultArray.getJSONObject(0);
            BigDecimal closePx = new BigDecimal(data.getString("c"));

            log.info("========== Gate K线 ==========");
            log.info("n:{} t:{} o:{} h:{} l:{} c:{} v:{} a:{} w:{}",
                    data.getString("n"), DateUtil.TimeStampToDateTime(data.getLong("t")),
                    data.getString("o"), data.getString("h"), data.getString("l"),
                    data.getString("c"), data.getString("v"), data.getString("a"),
                    data.getBooleanValue("w"));
            log.info("==============================");
            log.info("========== Gate K线数据 ==========");
            log.info("名称: {} 时间: {}", data.getString("n"), DateUtil.TimeStampToDateTime(data.getLong("t")));
            log.info("收盘: {} 已完结: {}",data.getString("c"),data.getBooleanValue("w"));
            log.info("==================================");

            if (gridTradeService != null) gridTradeService.onKline(closePx);
        } catch (Exception e) { log.error("[{}] handle fail", CHANNEL_NAME, e); }
            if (gridTradeService != null) {
                gridTradeService.onKline(closePx);
            }
        } catch (Exception e) { log.error("[{}] 处理数据失败", CHANNEL_NAME, e); }
        return true;
    }
}