using ScadaLink.Commons.Entities.Audit;
using ScadaLink.Commons.Types;
using ScadaLink.Commons.Types.Audit;

namespace ScadaLink.CentralUI.Services;

/// <summary>
/// CentralUI facade over <see cref="ScadaLink.Commons.Interfaces.Repositories.IAuditLogRepository"/>
/// (#23 M7-T3). The Audit Log page's results grid talks to this service rather than
/// the repository directly so tests can substitute a fake without spinning up EF
/// Core, and so a future caching / shaping layer (e.g. server-side CSV streaming)
/// can hang off the same seam.
/// </summary>
public interface IAuditLogQueryService
{
    /// <summary>
    /// Returns a keyset-paged result page for <paramref name="filter"/>. When
    /// <paramref name="paging"/> is <c>null</c>, defaults to <see cref="DefaultPageSize"/>
    /// rows with no cursor (first page). The repository orders by
    /// <c>(OccurredAtUtc DESC, EventId DESC)</c>; pass the last row's
    /// <see cref="AuditEvent.OccurredAtUtc"/> + <see cref="AuditEvent.EventId"/>
    /// back as the cursor for the next page.
    /// </summary>
    Task<IReadOnlyList<AuditEvent>> QueryAsync(
        AuditLogQueryFilter filter,
        AuditLogPaging? paging = null,
        CancellationToken ct = default);

    /// <summary>Default page size when callers don't specify one.</summary>
    int DefaultPageSize { get; }

    /// <summary>
    /// Audit Log (#23) M7 Bundle E (T13) — returns the point-in-time KPI snapshot
    /// the Health dashboard's Audit tiles render. Composes:
    /// <list type="bullet">
    ///   <item><c>TotalEventsLastHour</c> + <c>ErrorEventsLastHour</c> from
    ///   <see cref="ScadaLink.Commons.Interfaces.Repositories.IAuditLogRepository.GetKpiSnapshotAsync"/>
    ///   (1-hour trailing window).</item>
    ///   <item><c>BacklogTotal</c> from the sum of every site's
    ///   <c>SiteHealthReport.SiteAuditBacklog.PendingCount</c> via
    ///   <see cref="ScadaLink.HealthMonitoring.ICentralHealthAggregator"/>.</item>
    /// </list>
    /// </summary>
    /// <remarks>
    /// Repository + aggregator are read independently; if either source has no
    /// data the corresponding field is zero (a real signal — "no events" vs
    /// "no backlog" — rather than an error). The service does NOT swallow
    /// exceptions; the page wraps the call in a try/catch so a transient DB
    /// outage degrades the tile group to "unavailable" rather than killing the
    /// dashboard.
    /// </remarks>
    Task<AuditLogKpiSnapshot> GetKpiSnapshotAsync(CancellationToken ct = default);
}