"""Abstrakcyjny interfejs dostawcy danych (wzorzec Repository/Strategy).

To jest klucz do "łatwej migracji do SQL". Warstwa bazodanowa udostępnia na
zewnątrz tylko ten kontrakt. Dziś realizuje go ExcelDataProvider, jutro
SqlDataProvider — bez żadnej zmiany w warstwie logicznej i prezentacji.
"""
from __future__ import annotations

from abc import ABC, abstractmethod

from app.models import HealthInfo, SearchQuery, SearchResult


class DataProvider(ABC):
    name: str = "base"

    @abstractmethod
    def search(self, query: SearchQuery) -> SearchResult:
        """Wyszuka dane i zwróci je w górę. JEDYNE zadanie tej warstwy."""

    @abstractmethod
    def health(self) -> HealthInfo:
        ...

    def warmup(self) -> None:
        """Opcjonalne wstępne zbudowanie cache/indeksu przy starcie."""
        return None

    def list_bases(self) -> list[dict]:
        """Bazy widoczne dla dostawcy + metaopis i stan włączenia (DAN-15/PRE-09).

        Opcjonalne: dostawca SQL nie operuje na plikach, więc domyślnie pusto —
        UI pokaże wtedy, że nie ma czego przełączać, zamiast się wywrócić."""
        return []