using SchotzIadKmTracker.Api.Models.DTOs;

namespace SchotzIadKmTracker.Api.Services;

/// <summary>
/// Logique métier des Montant_Regle (montants effectivement versés, saisis par l'utilisateur)
/// et du Montant_Previsionnel (indication de versement à 80% du barème, purement informative).
/// </summary>
public interface IMontantRegleService
{
    /// <summary>
    /// Enregistre ou met à jour (upsert) le Montant_Regle pour un couple (année, mois, véhicule).
    /// S'il existe déjà une ligne pour la même (Annee, Mois, VehiculeId), elle est mise à jour ;
    /// sinon une nouvelle ligne est insérée (Property 26, Exigences 14.1/14.2/14.3).
    /// Rejette un montant négatif via <see cref="Exceptions.MontantRegleNegatifException"/> (Exigence 14.4).
    /// </summary>
    Task<MontantRegleDto> UpsertMontantRegleAsync(
        MontantRegleDto dto, CancellationToken cancellationToken = default);

    /// <summary>
    /// Retourne les Montant_Regle saisis pour une (année, véhicule), triés par mois croissant.
    /// Destiné au controller et au service de régularisation.
    /// </summary>
    Task<IReadOnlyList<MontantRegleDto>> GetMontantsReglesAsync(
        int annee, int vehiculeId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Calcule le Montant_Previsionnel indicatif pour un (année, mois, véhicule) :
    /// la tranche de barème est déterminée par le Total_Annuel_Partiel du véhicule (somme des
    /// distances arrondies de l'année pour ce véhicule jusqu'au mois indiqué inclus — Exigence 7.2),
    /// puis son coefficient/base est appliqué au seul kilométrage arrondi du mois affiché pour
    /// obtenir le Montant_Previsionnel_Mensuel (80%, Exigences 6.1/6.2/7.1/7.4), et au cumul annuel
    /// pour obtenir le Montant_Previsionnel_Annuel (100%, Exigences 8.1/8.2/8.5), tous deux arrondis
    /// à deux décimales.
    /// Ces valeurs sont purement informatives et n'entrent jamais dans la régularisation.
    /// </summary>
    Task<MontantPrevisionnelDto> GetMontantPrevisionnelAsync(
        int annee, int mois, int vehiculeId, CancellationToken cancellationToken = default);
}