using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Calcul des totaux du Panneau_Totaux (jour, mois, Total_Annuel_Partiel) filtrés par véhicule
/// et fourniture des données de navigation temporelle (années, mois et jours disponibles).
/// </summary>
public interface ITotauxService
{
    /// <summary>
    /// Calcule, pour la <paramref name="date"/> sélectionnée et le véhicule indiqué, les totaux
    /// kilométriques affichés dans le Panneau_Totaux (Exigences 12.7, 12.8, 12.19) :
    /// <list type="bullet">
    /// <item><description>TotalJour : somme des distances des Trajets de la journée.</description></item>
    /// <item><description>TotalMois : somme des distances des Trajets du mois de la date.</description></item>
    /// <item><description>TotalAnnuelPartiel : cumul de l'année jusqu'au mois de la date inclus,
    /// à l'exclusion des mois strictement postérieurs (Property 17).</description></item>
    /// </list>
    /// Les distances nulles sont comptées comme 0 et tous les totaux sont arrondis à 2 décimales.
    /// Seuls les Trajets du véhicule sont additionnés (Property 21).
    /// Si <paramref name="vehiculeId"/> vaut <c>null</c>, le Véhicule_Courant est utilisé
    /// (via <see cref="IVehiculeService.GetVehiculeCourantAsync"/>).
    /// </summary>
    Task<TotauxDto> GetTotauxAsync(DateOnly date, int? vehiculeId = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Retourne la liste des années comportant au moins un Trajet, à laquelle est ajoutée
    /// l'année courante si elle n'y figure pas déjà (Exigence 12.15). Liste triée croissante.
    /// </summary>
    Task<IReadOnlyList<int>> GetAnneesDisponiblesAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Retourne la liste des mois (1..12) de l'année <paramref name="annee"/> comportant au moins
    /// un Trajet (Exigence 12.16). Liste triée croissante.
    /// </summary>
    Task<IReadOnlyList<int>> GetMoisDisponiblesAsync(int annee, CancellationToken cancellationToken = default);

    /// <summary>
    /// Retourne la liste des jours du mois <paramref name="mois"/> de l'année <paramref name="annee"/>
    /// comportant au moins un Trajet (Exigence 12.16). Liste triée croissante.
    /// </summary>
    Task<IReadOnlyList<int>> GetJoursDisponiblesAsync(int annee, int mois, CancellationToken cancellationToken = default);
}