/*
|-------------------------------------------------------------------------------|
| Central Email Log |
| ------------------------------------------------------------------------ |
| Every outbound mail in the system writes one MasterEmailLog row per send |
| operation and one MasterEmailLogDetails row per recipient, so that a later |
| retry can target only the recipients that actually failed. |
|-------------------------------------------------------------------------------|
*/
using Ease.Core.Model;
using HRM.BO.Configuration;
using System;
using System.Collections.Generic;
namespace HRM.BO
{
#region MasterEmailLog
///
/// The header of one send operation: what was sent, to how many people,
/// how many of them it reached.
///
public class MasterEmailLog : AuditTrailBase
{
#region Constructor
public MasterEmailLog()
{
EmailType = EnumEmailType.None;
Description = string.Empty;
ParameterJson = string.Empty;
BatchStatus = EnumEmailBatchStatus.Pending;
PreserveAttachment = true;
TotalCount = 0;
SuccessCount = 0;
FailedCount = 0;
SkippedCount = 0;
RetryCount = 0;
Details = new List();
}
#endregion
#region Properties
public EnumEmailType EmailType { get; set; }
public string Description { get; set; }
public int? PayrollTypeID { get; set; }
///
/// The inputs this batch was built from, serialised as JSON
/// (e.g. {"salaryMonth":"2026-03-31"}). Kept so a batch can be
/// understood - and re-created - long after it ran.
///
public string ParameterJson { get; set; }
public int TotalCount { get; set; }
public int SuccessCount { get; set; }
public int FailedCount { get; set; }
public int SkippedCount { get; set; }
public EnumEmailBatchStatus BatchStatus { get; set; }
public DateTime? StartTime { get; set; }
public DateTime? EndTime { get; set; }
public int RetryCount { get; set; }
public DateTime? LastRetryDate { get; set; }
///
/// When true the bytes that were actually mailed are stored on each
/// detail row, which lets any mail type be retried without knowing how
/// its document is produced. Turn it off for very large batches.
///
public bool PreserveAttachment { get; set; }
#endregion
#region Read-only / display properties
/// Set by the service so grids do not have to map the enum.
public string EmailTypeName { get; set; }
public string BatchStatusName { get; set; }
/// Who started the batch. Filled in only by the list query.
public string CreatedByName { get; set; }
public List Details { get; set; }
#endregion
}
#endregion
#region MasterEmailLogDetails
///
/// One recipient of one send operation, with the outcome for that recipient.
///
public class MasterEmailLogDetails : AuditTrailBase
{
#region Constructor
public MasterEmailLogDetails()
{
MailFrom = string.Empty;
MailTo = string.Empty;
CC = string.Empty;
Subject = string.Empty;
Body = string.Empty;
ErrorMessage = string.Empty;
SendStatus = EnumEmailSendStatus.Pending;
AttemptCount = 0;
}
#endregion
#region Properties
public int MasterEmailLogID { get; set; }
/// Null when the recipient is not an employee (candidate, external address).
public int? EmployeeID { get; set; }
/// Copied at send time so the log still reads correctly if the employee is edited later.
public string EmployeeNo { get; set; }
public string EmployeeName { get; set; }
public string MailFrom { get; set; }
public string MailTo { get; set; }
public string CC { get; set; }
public string Subject { get; set; }
public string Body { get; set; }
/// Null when this mail type carries no attachment.
public string AttachmentName { get; set; }
///
/// The exact bytes that were mailed. Null when the batch ran with
/// PreserveAttachment = false, or when there is no attachment at all.
/// Not loaded by list queries - use GetAttachment(detailID).
///
public byte[] AttachmentData { get; set; }
public DateTime? SalaryMonth { get; set; }
/// Generic hook for the mail type's own key: TaxParameterID, BonusID, ...
public int? ReferenceID { get; set; }
public EnumEmailSendStatus SendStatus { get; set; }
public string ErrorMessage { get; set; }
public DateTime? SentTime { get; set; }
public int AttemptCount { get; set; }
public DateTime? LastRetryDate { get; set; }
#endregion
#region Read-only / display properties
public string SendStatusName { get; set; }
public bool HasAttachment { get; set; }
#endregion
}
#endregion
#region Email dispatch request models
///
/// One recipient handed to . The caller
/// fills in the addressing and the message; the dispatcher owns everything
/// after that - logging, sending, error capture and status.
///
public class EmailRecipient
{
public EmailRecipient()
{
MailTo = string.Empty;
CC = string.Empty;
Subject = string.Empty;
Body = string.Empty;
}
public int? EmployeeID { get; set; }
public string EmployeeNo { get; set; }
public string EmployeeName { get; set; }
public string MailTo { get; set; }
public string CC { get; set; }
public string Subject { get; set; }
public string Body { get; set; }
public DateTime? SalaryMonth { get; set; }
public int? ReferenceID { get; set; }
///
/// Set by the caller when this recipient must not be attempted at all -
/// for example "Email address missing". The row is logged as Skipped
/// with this text instead of being silently dropped.
///
public string SkipReason { get; set; }
}
///
/// The attachment produced for one recipient. Returning null from the
/// resolver means "no attachment for this recipient", which is a normal
/// outcome - not every mail type carries a file.
///
public class EmailAttachmentInfo
{
public EmailAttachmentInfo()
{
}
public EmailAttachmentInfo(string fileName, byte[] data)
{
FileName = fileName;
Data = data;
}
public string FileName { get; set; }
public byte[] Data { get; set; }
}
///
/// Everything needed to run - and log - one send operation, for any mail type.
///
public class EmailDispatchRequest
{
public EmailDispatchRequest()
{
EmailType = EnumEmailType.None;
Description = string.Empty;
ParameterJson = string.Empty;
PreserveAttachment = true;
DelayBetweenMailsInMs = 500;
Recipients = new List();
}
public EnumEmailType EmailType { get; set; }
public string Description { get; set; }
public int? PayrollTypeID { get; set; }
public string ParameterJson { get; set; }
public bool PreserveAttachment { get; set; }
/// Pause between two mails so the SMTP server is not flooded.
public int DelayBetweenMailsInMs { get; set; }
public int UserID { get; set; }
public List Recipients { get; set; }
///
/// Produces the attachment for one recipient, or null when there is
/// none. Called inside the dispatcher's per-recipient try/catch, so a
/// document that fails to build is recorded against that one employee
/// and the batch carries on.
///
public Func AttachmentResolver { get; set; }
}
/// What a dispatch or retry run ended up doing.
public class EmailDispatchResult
{
public int MasterEmailLogID { get; set; }
public int TotalCount { get; set; }
public int SuccessCount { get; set; }
public int FailedCount { get; set; }
public int SkippedCount { get; set; }
public EnumEmailBatchStatus BatchStatus { get; set; }
}
#endregion
#region Service interfaces
public interface IMasterEmailLogService
{
MasterEmailLog Get(int id);
List Get(EnumEmailType emailType, int? payrollTypeID, DateTime fromDate, DateTime toDate);
MasterEmailLog GetWithDetails(int id);
List GetDetails(int masterEmailLogID);
List GetDetails(int masterEmailLogID, EnumEmailSendStatus sendStatus);
List GetDetailsByEmployee(int employeeID);
/// The stored bytes of one detail row, or null when nothing was kept.
byte[] GetAttachment(int masterEmailLogDetailsID);
///
/// Writes the header and every recipient row in one transaction, the
/// details through SqlBulkCopy. Returns the new MasterEmailLogID.
///
int SaveBatch(MasterEmailLog log, List details);
/// Stores the outcome of a single recipient, attachment included.
void UpdateDetailResult(MasterEmailLogDetails item);
///
/// Recounts the detail rows and writes TotalCount/SuccessCount/
/// FailedCount/SkippedCount plus the resulting batch status.
///
MasterEmailLog RefreshBatchCounters(int masterEmailLogID, bool markEnded, int? modifiedBy);
void MarkRetryStarted(int masterEmailLogID, int modifiedBy);
void Delete(int masterEmailLogID);
}
///
/// The single entry point every module should use to send mail to many
/// recipients. It logs before it sends, never lets one bad recipient stop
/// the run, and can replay just the failures of an earlier batch.
///
public interface IEmailDispatchService
{
///
/// Writes the header and every recipient row up front, so the batch is
/// already visible - and already complete - before the first mail goes
/// out. Returns the new MasterEmailLogID. Fast: one bulk insert.
///
int CreateBatch(EmailDispatchRequest request);
///
/// Runs the send loop for a batch created by .
/// Long-running; callers that do not want to block should start this on
/// its own thread and let the caller poll the log instead.
///
EmailDispatchResult ProcessBatch(int masterEmailLogID, EmailDispatchRequest request,
EmailSettings emailSettings);
/// CreateBatch followed by ProcessBatch, for callers happy to block.
EmailDispatchResult Send(EmailDispatchRequest request, EmailSettings emailSettings);
///
/// Re-sends only the Failed rows of an existing batch. Uses each row's
/// stored attachment; when the batch was run without preserving
/// attachments, is asked to
/// rebuild one (it may be null, in which case the mail goes out with
/// no file).
///
EmailDispatchResult RetryFailed(int masterEmailLogID, EmailSettings emailSettings, int userID,
Func attachmentResolver);
}
#endregion
}