package com.xcong.excoin.modules.okxApi;

import java.math.BigDecimal;

/**
 * OKX 策略通用接口 — WS 频道处理器的回调契约。
 *
 * <p>定义所有 OKX 交易策略必须实现的核心回调方法，使得不同的策略实现
 * 可以无缝接入相同的 WebSocket 基础设施。
 *
 * <h3>实现类</h3>
 * <ul>
 *   <li>{@link OkxProfitRecycleStrategy} — 盈利回收循环策略</li>
 * </ul>
 *
 * <h3>WS 回调映射</h3>
 * <table>
 *   <tr><th>WS频道</th><th>回调方法</th><th>说明</th></tr>
 *   <tr><td>mark-price</td><td>onKline / setMarkPrice</td><td>价格驱动 + PnL计算</td></tr>
 *   <tr><td>positions</td><td>onPositionUpdate</td><td>仓位变更通知</td></tr>
 *   <tr><td>orders</td><td>onAutoOrder</td><td>条件单状态变更</td></tr>
 * </table>
 *
 * @author Administrator
 */
public interface IOkxStrategy {

    /**
     * K线/价格数据回调（公开频道 mark-price 推送）。
     *
     * @param price 最新价格（标记价或最新价）
     */
    void onKline(BigDecimal price);

    /**
     * 标记价格设置（用于 PnL 计算）。
     *
     * @param markPrice 标记价格
     */
    void setMarkPrice(BigDecimal markPrice);

    /**
     * 仓位更新回调（私有频道 positions 推送）。
     *
     * @param contract   合约名称
     * @param direction  交易方向（LONG / SHORT）
     * @param size       持仓张数（绝对值）
     * @param entryPrice 开仓均价
     */
    void onPositionUpdate(String contract, Direction direction,
                          BigDecimal size, BigDecimal entryPrice);

    /**
     * 自动订单状态变更回调（私有频道 orders 推送）。
     *
     * @param orderId   条件单算法 ID（algoId）
     * @param status    订单状态（如 "finished"）
     * @param reason    状态原因（如 "filled"）
     * @param orderType 订单类型（如 "entry-long", "plan-close-long-position"）
     * @param tradeId   成交 ID
     */
    void onAutoOrder(String orderId, String status, String reason,
                     String orderType, String tradeId);

    /**
     * 策略是否处于活跃状态（非 STOPPED/WAITING_KLINE）。
     *
     * @return true 表示策略正在运行
     */
    boolean isStrategyActive();

    /**
     * 保存 WS 客户端引用（用于判断订阅状态）。
     *
     * @param wsClient OKX WebSocket 客户端
     */
    void setWsClient(OkxKlineWebSocketClient wsClient);
}