DigitalData.Core/DigitalData.Core.Contracts/Application/IServiceMessage.cs

using System.Text.Json.Serialization;

namespace DigitalData.Core.Contracts.Application
{
    /// <summary>
    /// Defines a structured format for service messages, categorizing them into success indicators and various types of messages.
    /// This interface segregates messages into client-facing messages and different levels of logging messages, facilitating targeted communications and diagnostics.
    /// </summary>
    public interface IServiceMessage
    {
        /// <summary>
        /// Gets or sets a flag indicating whether the service operation was successful.
        /// </summary>
        bool IsSuccess { get; set; }

        /// <summary>
        /// Gets or sets a collection of messages intended for client display. This is intended to replace the deprecated 'Messages' property.
        /// </summary>
        List<string> ClientMessages { get; set; }

        /// <summary>
        /// [Obsolete("Deprecated: Use ClientMessages instead.")]
        /// Gets or sets a collection of messages associated with the service operation. These messages can be error descriptions,
        /// success notifications, or other relevant information related to the operation's outcome.
        /// </summary>
        [Obsolete("Deprecated: Use ClientMessages instead.")]
        List<string> Messages { get; set; }

        /// <summary>
        /// Gets or sets a collection of messages used for tracing program execution at a fine-grained level. These are typically voluminous and detailed.
        /// </summary>
        [JsonIgnore]
        List<string> TraceMessages { get; set; }

        /// <summary>
        /// Gets or sets a collection of messages helpful for debugging during development. These messages are often diagnostic.
        /// </summary>
        [JsonIgnore]
        List<string> DebugMessages { get; set; }

        /// <summary>
        /// Gets or sets a collection of informational messages, less critical than warnings, generally used for non-critical notifications.
        /// </summary>
        [JsonIgnore]
        List<string> InformationMessages { get; set; }

        /// <summary>
        /// Gets or sets a collection of messages indicating potential issues that are not necessarily errors, but which may require attention.
        /// </summary>
        [JsonIgnore]
        List<string> WarningMessages { get; set; }

        /// <summary>
        /// Gets or sets a collection of error messages indicating failures or problems within the service.
        /// </summary>
        [JsonIgnore]
        List<string> ErrorMessages { get; set; }

        /// <summary>
        /// Gets or sets a collection of messages indicating critical issues that require immediate attention.
        /// </summary>
        [JsonIgnore]
        List<string> CriticalMessages { get; set; }

        /// <summary>
        /// Adds a new message to the appropriate collection based on the message type.
        /// </summary>
        /// <param name="message">The message to add.</param>
        /// <returns>The current instance of IServiceMessage, allowing for method chaining.</returns>
        IServiceMessage WithMessage(string message);

        /// <summary>
        /// Adds a message corresponding to a specified message key to the appropriate collection, facilitating localization and standardization.
        /// </summary>
        /// <param name="messageKey">The enum value representing the message key.</param>
        /// <returns>The current instance of IServiceMessage, allowing for method chaining.</returns>
        IServiceMessage WithMessageKey(Enum messageKey);
    }
}