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

using System.Security.Claims;

namespace SeaHaven.Services.Interfaces
{
    /// <summary>
    /// Server-derived work-order account scope (SH-221): claims for authenticated callers,
    /// unique Accounts.Name ↔ Customer for org-wide / unauthenticated creates.
    /// </summary>
    public interface IWorkOrderAccountResolver
    {
        /// <summary>
        /// Account filter for reads. Null = org-wide (skip ApplyAccountScope).
        /// Throws Forbidden when scope is Missing.
        /// </summary>
        int? ResolveAccountFilter(ClaimsPrincipal user);

        /// <summary>
        /// Authenticated create: claim account_id, or org-wide Customer unique match.
        /// Missing scope → Forbidden. Unresolvable org-wide Customer → AccountUnresolved.
        /// </summary>
        Task<int> ResolveForAuthenticatedCreateAsync(
            ClaimsPrincipal user,
            string? customer,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Ingest/webhook/sync create: unique Customer → Accounts.Id or AccountUnresolved.
        /// </summary>
        Task<int> ResolveForUnauthenticatedCreateAsync(
            string? customer,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Best-effort Customer lookup (no throw). Null when blank, missing, or ambiguous.
        /// </summary>
        Task<int?> TryResolveFromCustomerAsync(
            string? customer,
            CancellationToken cancellationToken = default);
    }
}