ScadaBridge/src/ScadaLink.Commons/Interfaces/Repositories/INotificationOutboxRepository.cs

using ScadaLink.Commons.Entities.Notifications;
using ScadaLink.Commons.Types.Notifications;

namespace ScadaLink.Commons.Interfaces.Repositories;

/// <summary>
/// Data access for the central notification outbox — the queue of <see cref="Notification"/>
/// rows the outbox actor drains, retries, and audits. Distinct from
/// <see cref="INotificationRepository"/>, which manages notification list configuration.
/// </summary>
/// <remarks>
/// Persistence model: <see cref="InsertIfNotExistsAsync"/> and <see cref="UpdateAsync"/> commit
/// internally, so each call is its own transaction — suited to the outbox actor committing one
/// row's status transition at a time. The standalone <see cref="SaveChangesAsync"/> is available
/// for callers that stage multiple changes and want to flush them together.
/// </remarks>
public interface INotificationOutboxRepository
{
    /// <summary>
    /// Inserts <paramref name="n"/> only if no row with the same
    /// <see cref="Notification.NotificationId"/> exists. Returns <c>true</c> when a new
    /// row was inserted, <c>false</c> when an existing row was left untouched.
    /// Commits internally — this call is its own transaction.
    /// </summary>
    /// <param name="n">The notification to insert.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if inserted, false if already exists.</returns>
    Task<bool> InsertIfNotExistsAsync(Notification n, CancellationToken cancellationToken = default);

    /// <summary>
    /// Returns notifications ready for a delivery attempt: <c>Pending</c> rows, plus
    /// <c>Retrying</c> rows whose <c>NextAttemptAt</c> is at or before <paramref name="now"/>.
    /// Terminal rows are excluded. Ordered by <c>CreatedAt</c> ascending, capped at
    /// <paramref name="batchSize"/>.
    /// </summary>
    /// <param name="now">The current time for evaluating due retries.</param>
    /// <param name="batchSize">Maximum number of rows to return.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A list of notifications ready for delivery.</returns>
    Task<IReadOnlyList<Notification>> GetDueAsync(DateTimeOffset now, int batchSize, CancellationToken cancellationToken = default);

    /// <summary>Returns the notification with the given id, or <c>null</c>.</summary>
    /// <param name="notificationId">The notification identifier.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The notification, or null if not found.</returns>
    Task<Notification?> GetByIdAsync(string notificationId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Marks <paramref name="n"/> modified and persists it (status transitions).
    /// Commits internally — this call is its own transaction.
    /// </summary>
    /// <param name="n">The notification to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpdateAsync(Notification n, CancellationToken cancellationToken = default);

    /// <summary>
    /// Returns a page of notifications matching <paramref name="filter"/>, ordered by
    /// <c>CreatedAt</c> descending, together with the total matching count.
    /// </summary>
    /// <param name="filter">The query filter.</param>
    /// <param name="pageNumber">The page number (1-based).</param>
    /// <param name="pageSize">The page size.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A tuple of rows and total count.</returns>
    Task<(IReadOnlyList<Notification> Rows, int TotalCount)> QueryAsync(
        NotificationOutboxFilter filter, int pageNumber, int pageSize, CancellationToken cancellationToken = default);

    /// <summary>
    /// Bulk-deletes terminal rows (Delivered/Parked/Discarded) whose <c>CreatedAt</c> is
    /// older than <paramref name="cutoff"/>. Returns the number of rows deleted.
    /// </summary>
    /// <param name="cutoff">The cutoff time for deletion.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The number of rows deleted.</returns>
    Task<int> DeleteTerminalOlderThanAsync(DateTimeOffset cutoff, CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes a point-in-time <see cref="NotificationKpiSnapshot"/>. The stuck and
    /// delivered cutoffs are supplied by the caller; the current time used for
    /// <c>OldestPendingAge</c> is captured inside the method.
    /// </summary>
    /// <param name="stuckCutoff">The time threshold for marking notifications as stuck.</param>
    /// <param name="deliveredSince">The time threshold for counting delivered notifications.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A KPI snapshot.</returns>
    Task<NotificationKpiSnapshot> ComputeKpisAsync(
        DateTimeOffset stuckCutoff, DateTimeOffset deliveredSince, CancellationToken cancellationToken = default);

    /// <summary>
    /// Computes a point-in-time <see cref="SiteNotificationKpiSnapshot"/> per source site.
    /// Sites with no notification rows at all are omitted. The stuck and delivered cutoffs
    /// are supplied by the caller; the current time used for <c>OldestPendingAge</c> is
    /// captured inside the method.
    /// </summary>
    /// <param name="stuckCutoff">The time threshold for marking notifications as stuck.</param>
    /// <param name="deliveredSince">The time threshold for counting delivered notifications.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A list of per-site KPI snapshots.</returns>
    Task<IReadOnlyList<SiteNotificationKpiSnapshot>> ComputePerSiteKpisAsync(
        DateTimeOffset stuckCutoff, DateTimeOffset deliveredSince, CancellationToken cancellationToken = default);

    /// <summary>
    /// Persists pending changes tracked on the underlying context. Use this when staging
    /// multiple changes for a single commit; the individual mutating methods on this
    /// interface already commit on their own.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The number of changes persisted.</returns>
    Task<int> SaveChangesAsync(CancellationToken cancellationToken = default);
}