#nullable enable
using Baya.Application.Models.Audit;
using Baya.Application.Models.Common;

namespace Baya.Application.Contracts.Audit;

/// <summary>
/// Explicit append-only audit writer, for recording a state change that has no tracked-entity row diff
/// (row-level changes on auditable entities are captured automatically by the SaveChanges interceptor).
/// The trail is immutable — there is no update or delete path.
/// </summary>
public interface IAuditLogger
{
    ValueTask WriteAsync(
        string entityType,
        string entityId,
        string action,
        IReadOnlyDictionary<string, object?>? changedFields = null,
        CancellationToken cancellationToken = default);

    ValueTask<PagedResult<AuditLogDto>> GetTrailAsync(
        string? entityType,
        string? entityId,
        int? actorUserId,
        string? action,
        System.DateTimeOffset? from,
        System.DateTimeOffset? to,
        int page,
        int pageSize,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Retention sweep (refinement-phase-9 §9.4): deletes audit rows past their retention window. Financial /
    /// compliance entity types (money + verification) keep a longer legal window than everyday rows. Processes the
    /// oldest rows first, capped at <paramref name="maxRowsPerRun"/> so a large backlog drains across runs without
    /// loading the whole table. Returns the number of rows deleted.
    /// </summary>
    ValueTask<int> PurgeExpiredAsync(
        int generalRetentionDays,
        int financialRetentionDays,
        IReadOnlyCollection<string> financialEntityTypes,
        int maxRowsPerRun,
        CancellationToken cancellationToken = default);
}
