shoc-backend/SeaHaven.Services/Interfaces/IWorkOrderStatusMapper.cs

namespace SeaHaven.Services.Interfaces
{
    /// <summary>
    /// Maps work order status between DB strings, API canonical values, and FE display labels.
    /// See docs/spikes/status-mapping.md (Gate G2).
    /// </summary>
    public interface IWorkOrderStatusMapper
    {
        /// <summary>Normalizes a raw DB/Sync value to API canonical status (enum name).</summary>
        string NormalizeToCanonical(string? dbStatus);

        /// <summary>Maps canonical status to Schedule Board display label (StatusDisplay).</summary>
        string ToDisplay(string canonical, bool isUnassigned = false);

        /// <summary>True when work order should not be treated as past due.</summary>
        bool IsTerminal(string canonical);

        /// <summary>All DB string variants that match a canonical filter value.</summary>
        IReadOnlyList<string> ExpandCanonicalForFilter(string canonical);

        /// <summary>Expands multiple canonical filters to distinct DB values for SQL IN clauses.</summary>
        IReadOnlyList<string> ExpandCanonicalFilters(IEnumerable<string>? canonicalStatuses);

        /// <summary>Fase 2 write path — persists legacy-compatible string (Blazor/Sync).</summary>
        string ToStorage(string canonical);

        /// <summary>Fase 2 write path — FE display label to storage string.</summary>
        string? FromDisplay(string? statusDisplay);
    }
}