namespace adas_core.Application.Services.Interfaces
{
    /// <summary>
    /// Contrato genérico para un proveedor de locks por clave.
    /// CacheService usará una implementación local en memoria.
    /// RedisService podría usar una distribuida (si fuera necesario).
    /// </summary>
    public interface ILockProvider
    {
        /// <summary>
        /// Intenta adquirir el lock para una clave dentro del timeout.
        /// </summary>
        /// <!-- aidoc-review:v1 severity=medium kind=missing_returns
        ///      "The method returns Task<bool> indicating whether the lock was acquired, but the documentation does not describe the return value." -->
        Task<bool> AcquireAsync(string key, TimeSpan timeout);

        /// <summary>
        /// Libera el lock para la clave (idempotente).
        /// </summary>
        /// <!-- aidoc:v1 sig=5956b6c -->
        Task ReleaseAsync(string key);
    }
}