meezi/src/Meezi.API/Services/IAuditLogService.cs

namespace Meezi.API.Services;

/// <summary>
/// One sensitive POS / management action to record. Actor and tenant fields are
/// resolved from the current request context when not supplied explicitly.
/// </summary>
public sealed record AuditEntry
{
    public required string Category { get; init; }
    public required string Action { get; init; }
    public required string Summary { get; init; }
    public string? EntityType { get; init; }
    public string? EntityId { get; init; }

    /// <summary>Optional branch override; defaults to the active branch from context.</summary>
    public string? BranchId { get; init; }

    /// <summary>Optional structured payload — serialized to JSON.</summary>
    public object? Details { get; init; }

    /// <summary>Optional actor name override (display only).</summary>
    public string? ActorName { get; init; }
}

/// <summary>
/// Writes immutable audit-trail entries for sensitive actions. Implementations
/// must never throw into the caller — a failed audit write must not abort the
/// business operation it records.
/// </summary>
public interface IAuditLogService
{
    Task LogAsync(AuditEntry entry, CancellationToken ct = default);
}