"""Futures indicator calculator interface.

期货衍生指标计算器抽象接口（Track B）。
"""

from abc import ABC, abstractmethod

import pandas as pd


class FuturesIndicatorCalculator(ABC):
    """Futures indicator calculator interface.

    期货衍生指标计算器抽象接口（Track B）。

    Inputs are standardized DataFrames from futures providers.
    """

    @abstractmethod
    def get_oi_change(self, oi_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate open interest change.

        Args:
            oi_df: DataFrame with [timestamp, open_interest].

        Returns:
            pd.DataFrame: [timestamp, open_interest, open_interest_change]

        Raises:
            ValueError: If required columns are missing.
        """
        pass

    @abstractmethod
    def get_price_oi_divergence(
        self, close_df: pd.DataFrame, oi_df: pd.DataFrame
    ) -> pd.DataFrame:
        """Analyze price vs open interest divergence.

        分析价格与持仓量背离信号。

        Args:
            close_df: Price series with [timestamp, close].
            oi_df: OI series with [timestamp, open_interest].

        Returns:
            pd.DataFrame: [timestamp, close, open_interest, signal]

        Raises:
            ValueError: If inputs cannot be aligned.
        """
        pass

    @abstractmethod
    def get_vwap(self, ohlcv_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate VWAP.

        Args:
            ohlcv_df: OHLCV DataFrame.

        Returns:
            pd.DataFrame: [timestamp, vwap]

        Raises:
            ValueError: If required columns are missing.
        """
        pass

    @abstractmethod
    def get_term_structure(self, quotes_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate term structure metrics.

        计算期限结构指标（曲线斜率、升贴水结构等）。

        Args:
            quotes_df: Multi-contract quote snapshot with [contract, price, timestamp].

        Returns:
            pd.DataFrame: [timestamp, curve_slope, curve_level]

        Raises:
            ValueError: If required columns are missing.
        """
        pass

    @abstractmethod
    def get_spread(self, near_df: pd.DataFrame, far_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate inter-contract spread.

        计算跨合约价差。

        Args:
            near_df: Near contract series with [timestamp, close].
            far_df: Far contract series with [timestamp, close].

        Returns:
            pd.DataFrame: [timestamp, spread]

        Raises:
            ValueError: If inputs cannot be aligned.
        """
        pass

    @abstractmethod
    def get_long_short_ratio(self, rank_df: pd.DataFrame) -> pd.DataFrame:
        """Calculate long/short ratio from position ranking data.

        根据持仓排名数据计算多空比。

        Args:
            rank_df: Position ranking DataFrame.

        Returns:
            pd.DataFrame: [date, exchange, variety, contract, long_short_ratio]

        Raises:
            ValueError: If required columns are missing.
        """
        pass
