"""平台适配器基类。

多平台支持通过继承 BalanceProvider 实现：
1. 新建 app/providers/<name>.py
2. 继承 BalanceProvider，实现 build_request / extract_balance
3. 在 __init__.py 的 PROVIDERS 注册表中登记
"""

from __future__ import annotations

from abc import ABC, abstractmethod


class BalanceProvider(ABC):
    """一个平台的余额获取实现。"""

    #: 唯一标识（存入 platforms.provider_id）
    id: str = ""
    #: 平台显示名
    name: str = ""
    #: 默认货币单位
    currency: str = "USD"
    #: @lobehub/icons 键（前端品牌色映射）
    icon: str = ""
    #: 简要说明（前端展示）
    description: str = ""
    #: 请求方法
    method: str = "GET"

    @abstractmethod
    def build_request(self, api_key: str) -> tuple[str, dict, str | None]:
        """根据 api_key 构建请求，返回 (url, headers, body)。

        body 为 None 表示无请求体；POST 平台返回 JSON 字符串。
        """

    @abstractmethod
    def extract_balance(self, data: object) -> float:
        """从响应 JSON 中提取余额（数字），失败抛异常由上层记录。"""