qdr.app.studiou.orders2printpack/App/EmailStorage/Metadata.cs

using System.Text.Json.Serialization;

namespace qdr.app.studiou.orders2printpack.EmailStorage
{
    /// <summary>
    /// Root metadata container that holds information about the overall processing system
    /// and maintains a collection of individual email items. This is the main data structure
    /// that gets serialized to/from the metadata.json file.
    /// </summary>
    public class Metadata
    {
        /// <summary>
        /// Timestamp when this metadata file was first created.
        /// This helps track the age of the processing batch and provides audit information.
        /// </summary>
        [JsonRequired]
        [JsonPropertyName("metadata-created")]
        public DateTime Created { get; set; } = DateTime.Now;
        
        /// <summary>
        /// Timestamp of the last modification to this metadata.
        /// Updated whenever items are added, removed, or their state changes.
        /// Null when no modifications have been made since creation.
        /// </summary>
        [JsonPropertyName("metadata-modified")]
        public DateTime? Modified { get; set; } = null;

        /// <summary>
        /// Collection of individual email items being processed.
        /// Each item represents one recipient with their associated files and processing state.
        /// </summary>
        [JsonRequired]
        [JsonPropertyName("items")]
        public List<MetadataItem> Items { get; set; } = new List<MetadataItem>();
    }

    /// <summary>
    /// Represents a single email item with all associated processing information.
    /// Contains details about the recipient, files, processing state, and email content.
    /// This is the core data structure that tracks each individual email through the workflow.
    /// </summary>
    public class MetadataItem
    {
        #region Directory and File Information

        /// <summary>
        /// Name of the directory containing files for this email item.
        /// Typically matches or is derived from the recipient's email address.
        /// Used to locate the source files for processing.
        /// </summary>
        [JsonPropertyName("directory-name")]
        [JsonRequired]
        public string DirectoryName { get; set; } = string.Empty;

        /// <summary>
        /// Current processing state of this email item.
        /// Tracks progression through Ready -> Processing -> Uploading -> Sending -> Sent.
        /// Can also be Error if something goes wrong.
        /// </summary>
        [JsonPropertyName("state")]
        [JsonRequired]
        public EmailStateEnum State { get; set; } = EmailStateEnum.Ready;

        #endregion

        #region Recipient Information

        /// <summary>
        /// Email address of the recipient who will receive the processed files.
        /// This is the primary identifier for the email item.
        /// </summary>
        [JsonPropertyName("email-address")]
        [JsonRequired]
        public string EmailAddress { get; set; } = string.Empty;

        #endregion

        #region Email Content

        /// <summary>
        /// Subject line for the email that will be sent to the recipient.
        /// Initially populated from the email template, may be personalized during processing.
        /// </summary>
        [JsonPropertyName("subject")]
        [JsonRequired]
        public string Subject { get; set; } = string.Empty;

        /// <summary>
        /// Body content of the email in HTML or plain text format.
        /// Initially from template, gets personalized with download links, passwords, etc.
        /// </summary>
        [JsonPropertyName("body")]
        [JsonRequired]
        public string Body { get; set; } = string.Empty;

        #endregion

        #region File and Attachment Information

        /// <summary>
        /// Filename of the compressed attachment that will be uploaded and sent.
        /// Generated during processing and includes timestamp for uniqueness.
        /// Example: "studioufoto_user_at_example_dot_com_20240530_143022.zip"
        /// </summary>
        [JsonPropertyName("attachment")]
        [JsonRequired]
        public string FileNameAttachment { get; set; } = string.Empty;

        /// <summary>
        /// Size of the compressed attachment file in bytes.
        /// Populated after compression is complete, used for upload progress tracking.
        /// </summary>
        [JsonPropertyName("attachment-size")]
        [JsonRequired]
        public int SizeAttachment { get; set; } = 0;

        /// <summary>
        /// Number of individual files (typically JPG images) contained within the compressed attachment.
        /// Derived from scanning the source directory during metadata update.
        /// </summary>
        [JsonPropertyName("attachment-content-count")]
        [JsonRequired]
        public int InternalFilesCount { get; set; } = 0;

        #endregion

        #region Business Logic

        /// <summary>
        /// Comma-separated list of order numbers extracted from the filenames.
        /// Used for business reference and included in email communications.
        /// Example: "1001,1002,1003" extracted from files like "1001_photo1.jpg", "1002_photo1.jpg"
        /// </summary>
        [JsonPropertyName("orders")]
        [JsonRequired]
        public string Orders { get; set; } = string.Empty;

        #endregion

        #region Upload and Download Information

        /// <summary>
        /// Permanent link URL where the recipient can download their files.
        /// Generated by the Temporary Shared Storage service after successful upload.
        /// This link is included in the email sent to the recipient.
        /// </summary>
        [JsonPropertyName("upload-permalink")]
        public string UploadPermalink { get; set; } = string.Empty;

        /// <summary>
        /// Password required to access the download link.
        /// Generated during upload process for security.
        /// Included in the email so recipient can access their files.
        /// </summary>
        [JsonPropertyName("download-password")]
        public string DownloadPassword { get; set; } = string.Empty;

        #endregion

        #region Audit and Tracking

        /// <summary>
        /// Timestamp when this item completed processing (compression and upload).
        /// Null until processing is complete, used for audit and performance tracking.
        /// </summary>
        [JsonPropertyName("processed-date")]
        public DateTime? ProcessedDate { get; set; }
        
        /// <summary>
        /// Timestamp when the email was successfully sent to the recipient.
        /// Null until email sending is complete, marks final completion of the workflow.
        /// </summary>
        [JsonPropertyName("sent-date")]
        public DateTime? SentDate { get; set; }
        
        /// <summary>
        /// Error message if processing failed at any stage.
        /// Null when no errors have occurred, populated when State is set to Error.
        /// Used for debugging and manual intervention.
        /// </summary>
        [JsonPropertyName("error-message")]
        public string? ErrorMessage { get; set; }

        #endregion
    }
}