package com.xcong.excoin.modules.okxApi.wsHandler;

import com.alibaba.fastjson.JSONObject;
import org.java_websocket.client.WebSocketClient;

/**
 * OKX WebSocket 频道处理器接口。
 *
 * <h3>定位</h3>
 * 每个 OKX 频道对应一个实现类。新增频道只需实现此接口，
 * 然后通过 {@code OkxKlineWebSocketClient.addPublicHandler()} 或
 * {@code addPrivateHandler()} 注册即可。
 *
 * <h3>与 Gate 版本的区别</h3>
 * OKX 的公开频道和私有频道使用不同的 WebSocket 端点（public/private），
 * 订阅格式为 {@code {"op":"subscribe","args":[{"channel":"candle1m","instId":"ETH-USDT-SWAP"}]}}，
 * 与 Gate 的 {@code event/payload} 格式不同。
 *
 * <h3>实现类</h3>
 * <ul>
 *   <li>{@code CandlestickOkxChannelHandler} — 公开频道，K线数据</li>
 *   <li>{@code AbstractOkxPrivateChannelHandler} — 私有频道抽象基类（separate WS + login auth）</li>
 *   <li>{@code PositionsOkxChannelHandler} — 私有频道，仓位更新</li>
 *   <li>{@code OrderAlgoOkxChannelHandler} — 私有频道，条件订单(algo)状态推送</li>
 * </ul>
 *
 * <h3>OKX 订阅确认格式</h3>
 * {@code {"event":"subscribe","arg":{"channel":"candle1m"}}} 表示订阅成功。
 *
 * <h3>OKX 数据推送格式</h3>
 * {@code {"arg":{"channel":"positions","instType":"SWAP"},"data":[...]}}。
 *
 * @author Administrator
 */
public interface OkxChannelHandler {

    /**
     * 频道名称，如 {@code "candle1m"}、{@code "positions"}、{@code "orders-algo"}。
     *
     * @return OKX 频道标识字符串
     */
    String getChannelName();

    /**
     * 交易对标识，如 {@code "ETH-USDT-SWAP"}。
     * OKX 订阅需要 instId 参数来指定订阅的交易对。
     *
     * @return OKX 格式的交易对标识
     */
    String getInstId();

    /**
     * 发送订阅请求到指定的 WebSocket 连接。
     *
     * <h3>公开频道格式</h3>
     * <pre>
     * {"op":"subscribe","args":[{"channel":"candle1m","instId":"ETH-USDT-SWAP"}]}
     * </pre>
     *
     * <h3>私有频道格式</h3>
     * <pre>
     * {"op":"subscribe","args":[{"channel":"positions","instType":"SWAP"}]}
     * </pre>
     *
     * @param ws 目标 WebSocket 客户端（公开或私有端点）
     */
    void subscribe(WebSocketClient ws);

    /**
     * 发送取消订阅请求到指定的 WebSocket 连接。
     *
     * @param ws 目标 WebSocket 客户端
     */
    void unsubscribe(WebSocketClient ws);

    /**
     * 处理频道推送消息。
     *
     * <h3>路由规则</h3>
     * 如果消息的 {@code arg.channel} 匹配当前处理器的频道名，
     * 则提取 {@code data} 数组并处理业务逻辑，返回 {@code true}；
     * 否则返回 {@code false}（让路由器继续遍历其他 handler）。
     *
     * @param response WebSocket 推送的完整 JSON
     * @return true 表示已处理（循环停止），false 表示频道不匹配（继续遍历下一个 handler）
     */
    boolean handleMessage(JSONObject response);

    /**
     * 是否已收到订阅成功确认（即收到 {@code event:"subscribe"} 响应）。
     *
     * @return true 表示订阅已确认
     */
    boolean isSubscribed();

    /**
     * 标记订阅已确认/未确认。
     *
     * @param subscribed true=已确认，false=未确认
     */
    void setSubscribed(boolean subscribed);
}