"""Options Greeks / IV derived data provider interface.

期权希腊值、隐含波动率与价值/风险分析等衍生数据提供方抽象接口（Track A）。
"""

from abc import ABC, abstractmethod

import pandas as pd


class OptionsGreeksDataProvider(ABC):
    """Abstract base class for options Greeks / IV derived data providers.

    期权希腊值、隐含波动率与价值/风险分析等衍生数据提供方抽象接口（Track A）。

    This interface wraps upstream pre-calculated datasets (e.g., AkShare)
    and normalizes them into stable ``pd.DataFrame`` schemas.

    Attributes:
        underlying_symbol: Optional underlying symbol (标的代码). Provider-specific.
    """

    def __init__(self, underlying_symbol: str | None = None) -> None:
        """Initialize the provider.

        Args:
            underlying_symbol: 标的代码 (e.g., '510300'). Optional and provider-specific.
        """
        self.underlying_symbol = underlying_symbol

    @abstractmethod
    def get_greeks(self, symbol_or_date: str) -> pd.DataFrame:
        """Fetch options Greeks data.

        获取期权希腊值数据。

        Args:
            symbol_or_date: Option contract symbol or trade date.
                - 合约代码示例: '10003045'
                - 交易日示例: '20240626' 或 '2024-06-26'

        Returns:
            pd.DataFrame:
            - symbol: 期权合约代码
            - date: 交易日
            - delta: Delta
            - gamma: Gamma
            - theta: Theta
            - vega: Vega
            - rho: Rho
            - iv: 隐含波动率
            - theoretical_value: 理论价值

        Raises:
            ValueError: If ``symbol_or_date`` is invalid.
        """
        pass

    @abstractmethod
    def get_risk_indicators(self, date: str) -> pd.DataFrame:
        """Fetch risk indicator table for a specific trade date.

        获取指定交易日的期权风险指标表（通常为交易所批量披露）。

        Args:
            date: 交易日, format 'YYYYMMDD' or 'YYYY-MM-DD'.

        Returns:
            pd.DataFrame:
            - date: 交易日
            - symbol: 期权合约代码
            - delta: Delta
            - gamma: Gamma
            - theta: Theta
            - vega: Vega
            - rho: Rho
            - iv: 隐含波动率

        Raises:
            ValueError: If ``date`` is invalid.
        """
        pass

    @abstractmethod
    def get_value_analysis(self) -> pd.DataFrame:
        """Fetch options value analysis table.

        获取期权价值分析表（时间价值、内在价值、隐含波动率、理论价格等）。

        Returns:
            pd.DataFrame:
            - symbol: 期权代码
            - time_value: 时间价值
            - intrinsic_value: 内在价值
            - iv: 隐含波动率
            - theoretical_value: 理论价格

        Raises:
            ValueError: If the request fails.
        """
        pass

    @abstractmethod
    def get_iv_by_series(self, symbol: str, date: str) -> pd.DataFrame:
        """Fetch implied volatility by contract series for commodity options.

        获取商品期权按合约系列披露的隐含波动率数据。

        Args:
            symbol: 商品期权品种名称 (e.g., '铝期权').
            date: 交易日, format 'YYYYMMDD' or 'YYYY-MM-DD'.

        Returns:
            pd.DataFrame:
            - symbol: 品种名称
            - date: 交易日
            - series: 合约系列
            - iv: 隐含波动率
            - volume: 成交量 (if available)
            - open_interest: 持仓量 (if available)

        Raises:
            ValueError: If inputs are invalid.
        """
        pass
