using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Logique métier des résumés kilométriques mensuels et annuels.
/// Les distances nulles (Trajet non calculé, Exigence 2.4) sont traitées comme 0 dans les totaux.
/// </summary>
public interface IResumeService
{
    /// <summary>
    /// Construit le Résumé_Mensuel d'un mois : liste des Trajets triés par date croissante puis
    /// par Position croissante, chacun avec sa Distance, et total kilométrique (somme des distances,
    /// null → 0) arrondi à 2 décimales (Property 1 — Exigences 3.2, 3.3, 6.5).
    /// Filtre par véhicule lorsque <paramref name="vehiculeId"/> est fourni ; sinon inclut tous les véhicules.
    /// </summary>
    /// <exception cref="Exceptions.ResumeParametreInvalideException">
    /// Levée si <paramref name="mois"/> ∉ [1, 12] ou <paramref name="annee"/> ∉ [2000, 2100] (Exigence 3.6).
    /// </exception>
    Task<ResumeMensuelDto> GetResumeMensuelAsync(
        int annee, int mois, int? vehiculeId = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Construit le Résumé_Annuel d'une année : toujours exactement 12 Résumés_Mensuels
    /// (mois 1..12, les mois vides ayant un total de 0,00), et total annuel égal à la somme
    /// des 12 totaux mensuels (Property 2, Property 7 — Exigences 4.2, 4.3, 4.4, 4.7, 6.6).
    /// Filtre par véhicule lorsque <paramref name="vehiculeId"/> est fourni ; sinon inclut tous les véhicules.
    /// </summary>
    /// <exception cref="Exceptions.ResumeParametreInvalideException">
    /// Levée si <paramref name="annee"/> ∉ [2000, 2100] (Exigence 3.6).
    /// </exception>
    Task<ResumeAnnuelDto> GetResumeAnnuelAsync(
        int annee, int? vehiculeId = null, CancellationToken cancellationToken = default);
}