/* |-------------------------------------------------------------------------------| | 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 }