using System.Threading;
using System.Threading.Tasks;
using UtopiaCanteenSystem.Models;

namespace UtopiaCanteenSystem.Services;

/// <summary>
/// Handles RFID scan logic: validation, timeout rules, and persisting scan records.
/// </summary>
public interface IRfidService
{
    /// <summary>
    /// Processes a scan for the given card ID. Applies configured timeout,
    /// saves to lunch_order_transactions if allowed, and returns result message.
    /// </summary>
    (bool Success, string Message) ProcessScan(string cardId);

    /// <summary>
    /// Processes a scan and also returns cooldown seconds remaining when blocked by timeout rules.
    /// </summary>
    ScanResult ProcessScanDetailed(string cardId);

    /// <summary>Returns the last scan record for display (e.g. dashboard).</summary>
    ScanRecord? GetLastScan();

    /// <summary>Returns the most recent scan records, newest first (for order history).</summary>
    IReadOnlyList<ScanRecord> GetLastScans(int count);

    /// <summary>Returns all scan records for today (local date), newest first.</summary>
    IReadOnlyList<ScanRecord> GetScansForToday();

    /// <summary>Returns the count of scans recorded today (local date).</summary>
    int GetTodayScanCount();

    /// <summary>
    /// Returns the count of scans recorded today (local date boundaries), asynchronously.
    /// </summary>
    Task<int> GetTodayScanCountAsync(CancellationToken cancellationToken = default);

    /// <summary>Returns total number of scans/orders recorded (all time).</summary>
    Task<int> GetTotalScanCountAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Returns total number of scans recorded for a given card ID (all time).
    /// Used to detect repeat scans by the same user.
    /// </summary>
    Task<int> GetTotalScanCountForCardAsync(string cardId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Returns number of scans recorded today (local day) for a given card ID.
    /// </summary>
    Task<int> GetTodayScanCountForCardAsync(string cardId, CancellationToken cancellationToken = default);
}