feat(notification-outbox): add NotificationOutbox repository

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

@@ -0,0 +1,57 @@
+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>
+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.
+    /// </summary>
+    Task<bool> InsertIfNotExistsAsync(Notification n, CancellationToken ct = 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>
+    Task<IReadOnlyList<Notification>> GetDueAsync(DateTimeOffset now, int batchSize, CancellationToken ct = default);
+
+    /// <summary>Returns the notification with the given id, or <c>null</c>.</summary>
+    Task<Notification?> GetByIdAsync(string notificationId, CancellationToken ct = default);
+
+    /// <summary>Marks <paramref name="n"/> modified and persists it (status transitions).</summary>
+    Task UpdateAsync(Notification n, CancellationToken ct = default);
+
+    /// <summary>
+    /// Returns a page of notifications matching <paramref name="filter"/>, ordered by
+    /// <c>CreatedAt</c> descending, together with the total matching count.
+    /// </summary>
+    Task<(IReadOnlyList<Notification> Rows, int TotalCount)> QueryAsync(
+        NotificationOutboxFilter filter, int pageNumber, int pageSize, CancellationToken ct = 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>
+    Task<int> DeleteTerminalOlderThanAsync(DateTimeOffset cutoff, CancellationToken ct = 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>
+    Task<NotificationKpiSnapshot> ComputeKpisAsync(
+        DateTimeOffset stuckCutoff, DateTimeOffset deliveredSince, CancellationToken ct = default);
+
+    /// <summary>Persists pending changes tracked on the underlying context.</summary>
+    Task<int> SaveChangesAsync(CancellationToken ct = default);
+}