from abc import ABC, abstractmethod
from typing import List

from src.domain.entities.kw_capping import KWCappingRecord


class KWCappingRepositoryInterface(ABC):
    """Contract for reading and bulk-updating KW capping records."""

    @abstractmethod
    def list_all(self) -> List[KWCappingRecord]:
        """Return all non-deleted KW capping tiers, ordered by KW ascending."""
        ...

    @abstractmethod
    def bulk_update(
        self,
        updates: List[KWCappingRecord],
        user_id: int,
    ) -> List[KWCappingRecord]:
        """Update max_approved_value for each KW tier in the list.

        Only existing rows are updated — new tiers cannot be created via this
        method, matching the original Laravel behaviour.  Returns the updated
        records.
        """
        ...