"""数据源适配器公共协议。"""

from __future__ import annotations

from typing import List, Protocol

from sidecar.models import KlineBar, Snapshot


class MarketDataSource(Protocol):
    """行情数据源协议。"""

    def fetch_kline(self, symbol: str, period: str, limit: int) -> List[KlineBar]:
        """
        功能说明：从远端数据源获取 K 线。
        参数说明：symbol 为股票代码，period 为周期，limit 为最大条数。
        返回值说明：返回统一 KlineBar 列表。
        注意事项：不支持 K 线的数据源可抛出 NotImplementedError。
        """

    def fetch_snapshot(self, symbol: str) -> Snapshot:
        """
        功能说明：从远端数据源获取实时快照。
        参数说明：symbol 为股票代码。
        返回值说明：返回统一 Snapshot。
        注意事项：数据源字段缺失时用 None 表示。
        """