/// <summary>
/// Provides work queue views for each workflow stage.
/// Each queue returns batches filtered by status and sorted by submission time ASC.
/// </summary>
public interface IWorkQueueService
{
    /// <summary>
    /// Returns batches in PendingVerification status, sorted by UpdatedAt ASC (oldest first).
    /// This is the verifier's work queue — the next batch to verify is always at the top.
    /// </summary>
    Task<WorkQueueResponse> GetVerificationQueueAsync(
        int page, int pageSize, string sortBy = "updatedAt", string sortDirection = "asc");

    /// <summary>
    /// Returns batches that are awaiting or currently in data entry:
    /// - Status = InEntry (currently being entered)
    /// - Status = Rejected (returned for re-entry after verification rejection)
    /// Sorted by UpdatedAt ASC so rejected batches surface for re-entry.
    /// </summary>
    Task<WorkQueueResponse> GetEntryQueueAsync(
        int page, int pageSize, string sortBy = "updatedAt", string sortDirection = "asc");

    /// <summary>
    /// Returns batches in AwaitingClinicalApproval status, sorted by UpdatedAt ASC.
    /// This is the clinical approver's work queue.
    /// </summary>
    Task<WorkQueueResponse> GetClinicalApprovalQueueAsync(
        int page, int pageSize, string sortBy = "updatedAt", string sortDirection = "asc");

    /// <summary>
    /// Returns aggregate work queue health metrics for the supervisor dashboard.
    /// </summary>
    Task<WorkQueueOverviewResponse> GetOverviewAsync();
}