"""数据源抽象接口（可插拔核心）。

新增一个数据源只需：① 继承 DataSource 实现 fetch()；② 在 graph/sources/__init__.py
的 SOURCES 注册表里登记。config.yaml 通过 ``sources: [google_trends, pinterest]`` 决定启用哪些。
"""
from abc import ABC, abstractmethod
from typing import Any, Dict, List


class DataSource(ABC):
    #: 注册名（与 config.sources 中的字符串对应）
    name: str = "base"

    @abstractmethod
    def fetch(
        self,
        country: str,
        country_config: Dict[str, Any],
        global_config: Dict[str, Any],
    ) -> List[Dict[str, Any]]:
        """抓取该国热点，返回统一格式行。

        每行字段：``country, topic, seed, source, kind, raw_score``
        - source 标签用于后续权重与归一化（如 gt_trending / gt_style / gt_related / pinterest）
        - kind：trending / rising / top（用于按组归一化）
        - raw_score：Google Trends 相对指数 0-100，或 RSS 排名分

        实现内部必须自行处理限流/重试/异常，返回空列表也不应抛异常到上层。
        """
        raise NotImplementedError