shoc-backend/SeaHaven.DataServices/Interfaces/IUpliftDataService.cs

using Data.SeaHavenIndustries;

namespace SeaHaven.DataServices.Interfaces
{
    public interface IUpliftDataService
    {
        Task<(int TotalCount, IReadOnlyList<UpliftListItemData> Items)> GetPagedAsync(
            string? status, int? tier, int page, int pageSize, CancellationToken cancellationToken);
        Task<IReadOnlyList<UpliftForDispatchData>> GetForDispatchAsync(int dispatchId, CancellationToken cancellationToken);
        Task<IReadOnlyList<UpliftForWorkOrderData>> GetForWorkOrderAsync(int workOrderId, CancellationToken cancellationToken);
        Task<DispatchUpliftRequest?> GetByIdAndWorkOrderAsync(int requestId, int workOrderId, CancellationToken cancellationToken);
        Task<IReadOnlyList<PortalUpliftData>> GetForVendorDispatchAsync(int dispatchId, CancellationToken cancellationToken);
        Task<DispatchUpliftRequest?> GetByIdAsync(int id, CancellationToken cancellationToken);
        Task<int?> GetWorkOrderIdForUpliftAsync(int upliftRequestId, CancellationToken cancellationToken);
        Task<DispatchUpliftRequest?> GetByIdAndDispatchAsync(int requestId, int dispatchId, CancellationToken cancellationToken);
        // SH-101: server-side join of an uplift request with its linked evidence document.
        // Returns null when the request, the linked evidence, or the dispatch linkage is absent.
        Task<UpliftEvidenceDownloadData?> GetEvidenceForInternalDownloadAsync(int upliftRequestId, CancellationToken cancellationToken);
        Task<bool> HasPendingAsync(int dispatchId, CancellationToken cancellationToken);
        Task<bool> HasPendingForWorkOrderAsync(int workOrderId, CancellationToken cancellationToken);
        // SH-393: the tracked dispatch a work-order uplift is written to, resolved through the
        // same scope the work-order uplift reads use (non-deleted, owned or linked): the
        // work order's primary dispatch when it qualifies, otherwise its latest qualifying one.
        Task<Dispatch?> GetUpliftDispatchForWorkOrderAsync(int workOrderId, int? primaryDispatchId, CancellationToken cancellationToken);
        Task<decimal> SumAutoApprovedAmountForWorkOrderAsync(int workOrderId, CancellationToken cancellationToken);
        // Approval queue read contract: set-based per-work-order exposure totals covering
        // auto-approved and admin-approved uplift amounts (pending, rejected,
        // cancelled/withdrawn, and revoked requests are excluded). Work orders absent
        // from the result have no approved exposure.
        Task<IReadOnlyList<WorkOrderUpliftExposureData>> GetApprovedExposureForWorkOrdersAsync(
            IReadOnlyCollection<int> workOrderIds, CancellationToken cancellationToken);
        // SH-207: queue-wide pending exposure for the approvals header (sum of
        // RequestedNTE over non-deleted Pending requests on non-deleted dispatches).
        Task<decimal> GetPendingExposureTotalAsync(CancellationToken cancellationToken);
        // Stages (does not save) the cancellation of the work order's pending uplifts, each
        // with its own audit row, for the caller's unit of work. See PendingUpliftCancellation.
        Task<int> StageCancelPendingForWorkOrderAsync(
            int workOrderId,
            string? actorId,
            DateTime now,
            CancellationToken cancellationToken);
        // True when the work order is cancelled (PendingUpliftCancellation.IsCancelled), so no
        // new uplift may be requested on it.
        Task<bool> IsWorkOrderCancelledAsync(int workOrderId, CancellationToken cancellationToken);
        // SH-101: active = Pending or ChangesRequested (the only states that block a new request).
        Task<bool> HasActiveAsync(int dispatchId, CancellationToken cancellationToken);
        Task<DispatchUpliftRequest?> GetActiveRequestAsync(int dispatchId, CancellationToken cancellationToken);
        Task<DispatchUpliftRequest?> GetByRequestKeyAsync(int dispatchId, string requestKey, CancellationToken cancellationToken);
        Task<List<DispatchUpliftRequest>> GetDueForExpiryAsync(DateTime utcNow, int count, CancellationToken cancellationToken);
        Task<List<DispatchUpliftRequest>> GetDueForInitialNotificationAsync(int count, CancellationToken cancellationToken);
        Task<List<DispatchUpliftRequest>> GetDueForEscalationAsync(int count, CancellationToken cancellationToken);
        Task StageAsync(DispatchUpliftRequest request, CancellationToken cancellationToken);
        Task SaveChangesAsync(CancellationToken cancellationToken);
        Task<T> ExecuteWorkOrderMutationAsync<T>(
            int workOrderId,
            Func<CancellationToken, Task<T>> work,
            CancellationToken cancellationToken);
    }
}