using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Gestion du Cache_Adresses : recherche locale des adresses déjà connues, mise en cache
/// (upsert) des adresses géocodées et politique d'éviction LRU.
/// </summary>
public interface IAdresseCacheService
{
    /// <summary>
    /// Recherche locale des adresses en cache correspondant au fragment fourni.
    /// Retourne une liste vide si le fragment fait moins de 3 caractères (Requirement 9.3).
    /// Les suggestions sont ordonnées de la plus récemment utilisée à la plus ancienne.
    /// </summary>
    /// <param name="query">Fragment de recherche (min. 3 caractères).</param>
    /// <param name="limite">Nombre maximal de suggestions retournées (par défaut 5).</param>
    Task<IReadOnlyList<AdresseCacheDto>> RechercherLocalAsync(
        string query,
        int limite = 5,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Recherche l'entrée du cache correspondant exactement à l'adresse fournie (après normalisation).
    /// Utilisé lors de la création d'un Trajet pour éviter un appel BAN (Requirement 9.2).
    /// Met à jour la date de dernière utilisation de l'entrée trouvée.
    /// </summary>
    /// <returns>Les coordonnées et la géométrie si l'adresse est en cache, sinon <c>null</c>.</returns>
    Task<AdresseCacheEntreeDto?> ObtenirParAdresseAsync(
        string adresse,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Insère l'adresse dans le cache si elle est absente, sinon met uniquement à jour sa date de
    /// dernière utilisation sans modifier ses coordonnées (Requirements 9.1, 9.6). Applique ensuite
    /// la politique d'éviction LRU (Requirement 9.5). L'ensemble s'exécute en transaction.
    /// </summary>
    /// <param name="adresse">Libellé de l'adresse (sera normalisé pour le matching).</param>
    /// <param name="latitude">Latitude à utiliser si l'adresse est nouvelle.</param>
    /// <param name="longitude">Longitude à utiliser si l'adresse est nouvelle.</param>
    /// <param name="geometrieJson">Géométrie GeoJSON optionnelle si l'adresse est nouvelle.</param>
    Task UpsertAdresseAsync(
        string adresse,
        double latitude,
        double longitude,
        string? geometrieJson = null,
        CancellationToken cancellationToken = default);
}