first commit

src/Meezi.API/Services/IAuditLogService.cs

@@ -0,0 +1,33 @@
+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);
+}