namespace GestionIntegral.Api.Services.Comunicaciones
{
    public interface IEmailService
    {
        /// <summary>
        /// Envía un correo electrónico a un único destinatario, con la posibilidad de adjuntar un archivo.
        /// Este método también registra automáticamente el resultado del envío en la base de datos.
        /// </summary>
        /// <param name="destinatarioEmail">La dirección de correo del destinatario.</param>
        /// <param name="destinatarioNombre">El nombre del destinatario.</param>
        /// <param name="asunto">El asunto del correo.</param>
        /// <param name="cuerpoHtml">El contenido del correo en formato HTML.</param>
        /// <param name="attachment">Los bytes del archivo a adjuntar (opcional).</param>
        /// <param name="attachmentName">El nombre del archivo adjunto (requerido si se provee attachment).</param>
        /// <param name="origen">Identificador del proceso que dispara el email (ej. "EnvioManualPDF"). Para logging.</param>
        /// <param name="referenciaId">ID de la entidad relacionada (ej. "Factura-59"). Para logging.</param>
        /// <param name="idUsuarioDisparo">ID del usuario que inició la acción (si aplica). Para logging.</param>
        Task EnviarEmailAsync(
            string destinatarioEmail, 
            string destinatarioNombre, 
            string asunto, 
            string cuerpoHtml, 
            byte[]? attachment = null, 
            string? attachmentName = null,
            string? origen = null, 
            string? referenciaId = null, 
            int? idUsuarioDisparo = null);

        /// <summary>
        /// Envía un correo electrónico a un único destinatario, con la posibilidad de adjuntar múltiples archivos.
        /// Este método también registra automáticamente el resultado del envío en la base de datos.
        /// </summary>
        /// <param name="destinatarioEmail">La dirección de correo del destinatario.</param>
        /// <param name="destinatarioNombre">El nombre del destinatario.</param>
        /// <param name="asunto">El asunto del correo.</param>
        /// <param name="cuerpoHtml">El contenido del correo en formato HTML.</param>
        /// <param name="adjuntos">Una lista de tuplas que contienen los bytes y el nombre de cada archivo a adjuntar.</param>
        /// <param name="origen">Identificador del proceso que dispara el email (ej. "FacturacionMensual"). Para logging.</param>
        /// <param name="referenciaId">ID de la entidad relacionada (ej. "Suscriptor-3"). Para logging.</param>
        /// <param name="idUsuarioDisparo">ID del usuario que inició la acción (si aplica). Para logging.</param>
        Task EnviarEmailConsolidadoAsync(
            string destinatarioEmail, 
            string destinatarioNombre, 
            string asunto, 
            string cuerpoHtml, 
            List<(byte[] content, string name)> adjuntos,
            string? origen = null, 
            string? referenciaId = null, 
            int? idUsuarioDisparo = null);
    }
}