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,
    /// Location.AccountId for board create, unique Accounts.Name ↔ Customer for ingest/webhook.
    /// </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.
        /// Used by legacy AddWorkorder — not board create.
        /// </summary>
        Task<int> ResolveForAuthenticatedCreateAsync(
            ClaimsPrincipal user,
            string? customer,
            CancellationToken cancellationToken = default);

        /// <summary>
        /// Board create: stamp from JWT account_id or Location.AccountId. Never trusts body customer/accountId.
        /// Missing locationId → InvalidValue. Missing location → NotFound. Null Location.AccountId → AccountUnresolved.
        /// Scoped location mismatch → Forbidden.
        /// </summary>
        Task<int> ResolveForBoardCreateAsync(
            ClaimsPrincipal user,
            int? locationId,
            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);
    }
}