"""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