namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Orchestre le calcul de la distance d'un trajet à partir des adresses de départ et
/// d'arrivée et de leurs coordonnées éventuelles.
///
/// Logique :
/// <list type="bullet">
///   <item>Si les deux coordonnées sont connues → appel ORS ; en cas de timeout/échec ORS
///   → fallback orthodromique (Haversine), sans erreur pour l'utilisateur.</item>
///   <item>Si une coordonnée est absente → géocodage BAN de l'adresse manquante
///   (meilleur résultat) AVANT tout appel ORS ; ORS n'est jamais appelé avec des
///   coordonnées nulles (Property 16).</item>
///   <item>Si BAN ne peut pas résoudre (aucun résultat ou indisponible) → distance nulle
///   + avertissement, sans erreur bloquante, pour que l'appelant stocke la distance null.</item>
/// </list>
/// </summary>
public interface IDistanceCalculator
{
    /// <summary>
    /// Calcule la distance entre <paramref name="adresseDepart"/> et
    /// <paramref name="adresseArrivee"/>, en résolvant au besoin les coordonnées manquantes
    /// via BAN, puis en appelant ORS (avec fallback Haversine).
    /// </summary>
    /// <param name="adresseDepart">Texte de l'adresse de départ.</param>
    /// <param name="adresseArrivee">Texte de l'adresse d'arrivée.</param>
    /// <param name="departLatitude">Latitude de départ connue, ou <c>null</c>.</param>
    /// <param name="departLongitude">Longitude de départ connue, ou <c>null</c>.</param>
    /// <param name="arriveeLatitude">Latitude d'arrivée connue, ou <c>null</c>.</param>
    /// <param name="arriveeLongitude">Longitude d'arrivée connue, ou <c>null</c>.</param>
    /// <param name="cancellationToken">Jeton d'annulation.</param>
    /// <returns>Un <see cref="DistanceCalculationResult"/> (jamais d'exception bloquante).</returns>
    Task<DistanceCalculationResult> CalculerAsync(
        string adresseDepart,
        string adresseArrivee,
        double? departLatitude,
        double? departLongitude,
        double? arriveeLatitude,
        double? arriveeLongitude,
        CancellationToken cancellationToken = default);
}