using TrajetKmTracker.Api.Models.DTOs;

namespace TrajetKmTracker.Api.Services;

/// <summary>
/// Logique métier du profil utilisateur (singleton Id = 1) : lecture, sauvegarde avec
/// géocodage BAN de l'Adresse_Domicile et détermination de l'état de configuration (onboarding).
/// </summary>
public interface IProfilService
{
    /// <summary>
    /// Retourne le profil (singleton Id = 1). Crée l'enregistrement à la volée s'il est absent
    /// afin de garantir qu'un profil vide soit toujours disponible à la lecture.
    /// </summary>
    Task<ProfilDto> GetProfilAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Sauvegarde le profil. Géocode l'Adresse_Domicile via la BAN : en cas de succès, stocke les
    /// coordonnées et positionne <c>DomicileGeocode = true</c> (avec mise en cache de l'adresse) ;
    /// en cas d'échec BAN, persiste l'adresse textuelle sans coordonnées et <c>DomicileGeocode = false</c>
    /// sans lever d'exception (Requirements 10.2, 10.7, 10.8).
    /// </summary>
    Task<ProfilDto> SaveProfilAsync(SaveProfilDto dto, CancellationToken cancellationToken = default);

    /// <summary>
    /// Détermine l'état de configuration du profil (onboarding) :
    /// <c>EstConfigure = true</c> si et seulement si un Profil existe avec un Nom ET un Prénom non vides
    /// (après trim) ET qu'au moins un Véhicule existe (Property 31, Requirements 16.1, 16.2).
    /// </summary>
    Task<EtatProfilDto> GetEtatAsync(CancellationToken cancellationToken = default);
}