"""Equipment Repository Port (Domain Interface)."""

from __future__ import annotations

from datetime import date
from decimal import Decimal
from typing import Any, Protocol, runtime_checkable


@runtime_checkable
class EquipmentRepositoryPort(Protocol):
    """Port interface defining persistence and query operations for equipment and fuel telemetry."""

    def record_fuel_log(
        self,
        equipment_id: str,
        fill_date: date,
        fuel_quantity_liters: Decimal,
        unit_price_vnd: Decimal,
        total_cost_vnd: Decimal,
        odometer_hours: Decimal,
        source_invoice_id: str | None = None,
    ) -> dict[str, Any]:
        """Record an equipment fuel fill entry."""
        ...

    def get_equipment_by_id_or_code(self, identifier: str) -> dict[str, Any] | None:
        """Fetch equipment information by either ID or equipment_code."""
        ...

    def get_fuel_logs_by_equipment(self, equipment_id: str) -> list[dict[str, Any]]:
        """Fetch fuel fill logs for a specific equipment sorted chronologically."""
        ...

    def get_total_operated_hours(self, equipment_id: str) -> Decimal:
        """Fetch total hours operated from operational logs."""
        ...

    def get_fleet_counts(self) -> dict[str, Any]:
        """Fetch overall fleet equipment counts (trucks, excavators, operating)."""
        ...

    def get_fleet_fuel_totals(self) -> dict[str, Any]:
        """Fetch overall fleet fuel consumption totals from invoices/logs."""
        ...

    def get_fleet_equipment_summary(self) -> list[dict[str, Any]]:
        """Fetch aggregated equipment list with fuel totals and odometer stats."""
        ...

    def get_active_equipment_for_telematics(self, limit: int = 10) -> list[dict[str, Any]]:
        """Fetch active equipment along with their actual fuel and hour stats for telematics dashboard."""
        ...