using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Logique métier du barème kilométrique : CRUD des tranches, validation du non-chevauchement
/// par (année, puissance fiscale), sélection de tranche et calcul de montant.
/// </summary>
public interface IBaremeService
{
    /// <summary>Retourne toutes les tranches d'une année (toutes puissances fiscales confondues).</summary>
    Task<IReadOnlyList<TrancheBaremeDto>> GetBaremeAsync(int annee, CancellationToken cancellationToken = default);

    /// <summary>
    /// Ajoute une tranche. Rejette l'ajout s'il crée un chevauchement d'intervalle [KmMin, KmMax]
    /// pour la même (année, puissance fiscale) via <see cref="Exceptions.TranchesBaremeChevauchantesException"/>.
    /// </summary>
    Task<TrancheBaremeDto> AddTrancheAsync(SaveTrancheBaremeDto dto, CancellationToken cancellationToken = default);

    /// <summary>
    /// Met à jour une tranche existante. Rejette la mise à jour si elle crée un chevauchement
    /// (hors la tranche elle-même) via <see cref="Exceptions.TranchesBaremeChevauchantesException"/>.
    /// Lève <see cref="Exceptions.TrancheBaremeNotFoundException"/> si la tranche n'existe pas.
    /// </summary>
    Task<TrancheBaremeDto> UpdateTrancheAsync(int id, SaveTrancheBaremeDto dto, CancellationToken cancellationToken = default);

    /// <summary>
    /// Supprime une tranche. Lève <see cref="Exceptions.TrancheBaremeNotFoundException"/> si elle n'existe pas.
    /// </summary>
    Task DeleteTrancheAsync(int id, CancellationToken cancellationToken = default);

    /// <summary>
    /// Sélectionne la tranche dont [KmMin, KmMax] contient <paramref name="totalKm"/> pour la
    /// (année, puissance fiscale) donnée et calcule le montant `totalKm × Coefficient + Base`
    /// (Property 24/27). Si aucune tranche n'existe pour cette combinaison, retourne un montant nul
    /// et un signal « barème non configuré » sans lever d'erreur bloquante (Exigence 13.4).
    /// </summary>
    Task<BaremeCalculResult> CalculerMontantAsync(
        int annee, int puissanceFiscale, decimal totalKm, CancellationToken cancellationToken = default);

    /// <summary>
    /// Copie toutes les tranches de l'année la plus récente (strictement antérieure à
    /// <paramref name="anneeCible"/>) qui possède un barème, vers <paramref name="anneeCible"/>.
    /// Les tranches existantes de l'année cible sont d'abord supprimées (annule et remplace),
    /// en transaction. Retourne le nombre de tranches copiées. Retourne 0 si aucun barème
    /// antérieur n'existe (rien n'est modifié).
    /// </summary>
    Task<int> CopierDernierBaremeAsync(int anneeCible, CancellationToken cancellationToken = default);

    /// <summary>Retourne les années (triées croissantes) pour lesquelles au moins une tranche de barème existe.</summary>
    Task<IReadOnlyList<int>> GetAnneesAvecBaremeAsync(CancellationToken cancellationToken = default);
}