using JdeScoping.Domain.Models;

namespace JdeScoping.DataAccess.Services;

/// <summary>
/// Service for managing manual data sync requests.
/// </summary>
public interface IManualSyncRequestService
{
    /// <summary>
    /// Gets all manual sync requests, optionally filtered to pending only.
    /// </summary>
    /// <param name="pendingOnly">If true, returns only pending requests.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>A read-only list of manual sync requests.</returns>
    Task<IReadOnlyList<ManualSyncRequest>> GetRequestsAsync(
        bool pendingOnly = false,
        CancellationToken ct = default);

    /// <summary>
    /// Gets the next pending request in FIFO order (for processor).
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The next pending request, or null if none exists.</returns>
    Task<ManualSyncRequest?> GetNextPendingRequestAsync(CancellationToken ct = default);

    /// <summary>
    /// Creates a new manual sync request.
    /// </summary>
    /// <param name="pipelineName">The name of the ETL pipeline to sync.</param>
    /// <param name="syncType">The type of sync (mass, daily, hourly).</param>
    /// <param name="requestedBy">The username of the requester.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The created manual sync request.</returns>
    Task<ManualSyncRequest> CreateRequestAsync(
        string pipelineName,
        string syncType,
        string requestedBy,
        CancellationToken ct = default);

    /// <summary>
    /// Cancels a pending request using optimistic concurrency.
    /// Returns true if cancelled, false if already completed/cancelled.
    /// </summary>
    /// <param name="id">The request ID.</param>
    /// <param name="cancelledBy">The username of the user cancelling the request.</param>
    /// <param name="rowVersion">The row version for optimistic concurrency.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>True if the request was cancelled; false if already completed or cancelled.</returns>
    Task<bool> CancelRequestAsync(
        int id,
        string cancelledBy,
        byte[] rowVersion,
        CancellationToken ct = default);

    /// <summary>
    /// Marks a request as completed using optimistic concurrency.
    /// Called by the sync processor.
    /// </summary>
    /// <param name="id">The request ID.</param>
    /// <param name="rowVersion">The row version for optimistic concurrency.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>True if the request was marked completed; false if already completed or cancelled.</returns>
    Task<bool> CompleteRequestAsync(
        int id,
        byte[] rowVersion,
        CancellationToken ct = default);
}