namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Génération des Export_PDF (QuestPDF). Compose les services métier existants
/// (résumé, profil, véhicule, barème, montants réglés) pour produire les documents.
/// La génération est enveloppée dans un délai de 15 secondes ; en cas de dépassement
/// ou d'erreur de rendu, une <see cref="Exceptions.PdfGenerationException"/> est levée
/// (Exigence 7.5) — le controller la mappe vers <c>503 Service Unavailable</c>.
/// </summary>
public interface IPdfService
{
    /// <summary>
    /// Génère le rapport PDF mensuel d'un (année, mois) pour le véhicule indiqué (Exigences 7.1,
    /// 7.4, 7.6, 7.8, 7.10, 7.11). L'en-tête contient l'identité de l'utilisateur, le véhicule
    /// (plaque, puissance fiscale, coefficient et base de la tranche annuelle applicable), la
    /// période, l'adresse de départ du profil, le total kilométrique du mois, le total kilométrique
    /// annuel cumulé, le TOTAL IK du mois (km du mois × coefficient de la tranche annuelle) et le
    /// Montant_Regle du mois. Le corps liste les trajets (date, motif/commentaire, départ → arrivée, km).
    /// Le nom de fichier suggéré est <c>trajets_MM_AAAA.pdf</c>.
    /// </summary>
    /// <exception cref="Exceptions.PdfGenerationException">
    /// Levée en cas de dépassement du délai de 15 s ou d'échec de rendu (Exigence 7.5).
    /// </exception>
    Task<PdfResult> GenererRapportMensuelAsync(
        int annee, int mois, int vehiculeId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Génère la synthèse annuelle de régularisation d'une <paramref name="annee"/> pour le véhicule
    /// indiqué (Exigences 7.2, 7.4, 7.6, 7.7, 7.8, 7.12). La page de synthèse contient le nom et le
    /// prénom de l'utilisateur, l'année, l'adresse de domicile, le barème applicable de l'année (les
    /// trois tranches coefficient/base par puissance fiscale du véhicule), le véhicule et sa puissance
    /// fiscale, la tranche annuelle applicable ; puis pour chacun des douze mois : les kilomètres
    /// parcourus, le Montant_Regle (frais payé) et le Frais_Reel_Mensuel (frais réel). Les totaux
    /// (km annuel, total réglé, Montant_Reel, Regularisation) et la « formule réelle » sont indiqués.
    /// Le nom de fichier suggéré est <c>trajets_AAAA.pdf</c>.
    /// </summary>
    /// <exception cref="Exceptions.PdfGenerationException">
    /// Levée en cas de dépassement du délai de 15 s ou d'échec de rendu (Exigence 7.5).
    /// </exception>
    Task<PdfResult> GenererRapportAnnuelAsync(
        int annee, int vehiculeId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Détermine les véhicules ayant des Trajets pour l'<paramref name="annee"/> et génère un rapport
    /// annuel PDF distinct par véhicule (Exigence 7.9). Retourne un PDF par véhicule ayant des données,
    /// trié par identifiant de véhicule. Retourne une liste vide si aucun trajet n'existe pour l'année.
    /// </summary>
    /// <exception cref="Exceptions.PdfGenerationException">
    /// Levée en cas de dépassement du délai de 15 s ou d'échec de rendu (Exigence 7.5).
    /// </exception>
    Task<IReadOnlyList<PdfResult>> GenererRapportsAnnuelsParVehiculeAsync(
        int annee, CancellationToken cancellationToken = default);

    /// <summary>
    /// Détermine les véhicules ayant des Trajets pour le couple (<paramref name="annee"/>,
    /// <paramref name="mois"/>) et génère un rapport mensuel PDF distinct par véhicule (Exigence 7.9).
    /// Retourne un PDF par véhicule ayant des données, trié par identifiant de véhicule. Retourne une
    /// liste vide si aucun trajet n'existe pour la période.
    /// </summary>
    /// <exception cref="Exceptions.PdfGenerationException">
    /// Levée en cas de dépassement du délai de 15 s ou d'échec de rendu (Exigence 7.5).
    /// </exception>
    Task<IReadOnlyList<PdfResult>> GenererRapportsMensuelsParVehiculeAsync(
        int annee, int mois, CancellationToken cancellationToken = default);
}