feat(audit)!: ScadaBridge C3 — swap to canonical ZB.MOM.WW.Audit.AuditEvent across seams/emitters/DTO/redactor wiring; transitional 24-col storage shim (Task 2.5)

2026-06-02 12:37:50 -04:00
parent 5aaf9e2923
commit db707bb0de
127 changed files with 2240 additions and 3886 deletions
@@ -0,0 +1,113 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
+
+namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities;
+
+/// <summary>
+/// Transitional EF Core persistence shape for the central <c>dbo.AuditLog</c> table
+/// (Audit Log #23). This is the 24-column row formerly modelled by
+/// <c>ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit.AuditEvent</c>; in C3 (Task 2.5)
+/// the canonical <c>ZB.MOM.WW.Audit.AuditEvent</c> became the type at every seam,
+/// emit site, DTO boundary, and redactor, and this row type was relocated here as a
+/// storage-only entity so the existing table keeps working unchanged.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The repository maps canonical ⇄ this row at the persistence boundary via
+/// <c>ZB.MOM.WW.ScadaBridge.Commons.Types.Audit.AuditRowProjection</c>. C5 replaces
+/// this shim + table with the real DetailsJson-backed schema.
+/// </para>
+/// <para>
+/// All <c>*Utc</c>-suffixed <see cref="DateTime"/> properties are invariantly UTC
+/// (CLAUDE.md: "All timestamps are UTC throughout the system."). The init-setters
+/// force <see cref="DateTimeKind.Utc"/> on assignment so a value re-hydrated from a
+/// SQL Server <c>datetime2</c> column (which strips the <c>Kind</c> flag on the wire)
+/// cannot leak downstream as <see cref="DateTimeKind.Unspecified"/> or be silently
+/// re-interpreted as local time.
+/// </para>
+/// </remarks>
+public sealed record AuditLogRow
+{
+    /// <summary>Idempotency key; uniquely identifies one audit lifecycle event.</summary>
+    public Guid EventId { get; init; }
+
+    /// <summary>UTC timestamp when the audited action occurred at its source.</summary>
+    public DateTime OccurredAtUtc
+    {
+        get => _occurredAtUtc;
+        init => _occurredAtUtc = DateTime.SpecifyKind(value, DateTimeKind.Utc);
+    }
+    private readonly DateTime _occurredAtUtc;
+
+    /// <summary>UTC timestamp when the row was ingested at central; null on the site hot-path.</summary>
+    public DateTime? IngestedAtUtc
+    {
+        get => _ingestedAtUtc;
+        init => _ingestedAtUtc = value.HasValue
+            ? DateTime.SpecifyKind(value.Value, DateTimeKind.Utc)
+            : null;
+    }
+    private readonly DateTime? _ingestedAtUtc;
+
+    /// <summary>Trust-boundary channel the audited action crossed.</summary>
+    public AuditChannel Channel { get; init; }
+
+    /// <summary>Specific event kind within the channel.</summary>
+    public AuditKind Kind { get; init; }
+
+    /// <summary>Correlation id linking related audit rows (e.g. the cached-op lifecycle).</summary>
+    public Guid? CorrelationId { get; init; }
+
+    /// <summary>Id of the originating script execution / inbound request.</summary>
+    public Guid? ExecutionId { get; init; }
+
+    /// <summary>ExecutionId of the execution that spawned this run; null for top-level runs.</summary>
+    public Guid? ParentExecutionId { get; init; }
+
+    /// <summary>Site id where the action originated; null for central-direct events.</summary>
+    public string? SourceSiteId { get; init; }
+
+    /// <summary>The cluster node on which the event was emitted.</summary>
+    public string? SourceNode { get; init; }
+
+    /// <summary>Instance id where the action originated, when applicable.</summary>
+    public string? SourceInstanceId { get; init; }
+
+    /// <summary>Script that initiated the action, when applicable.</summary>
+    public string? SourceScript { get; init; }
+
+    /// <summary>Authenticated actor for inbound paths (API key name, user, etc.).</summary>
+    public string? Actor { get; init; }
+
+    /// <summary>Target of the action: external system name, db connection name, list name, or inbound method.</summary>
+    public string? Target { get; init; }
+
+    /// <summary>Lifecycle status of this row.</summary>
+    public AuditStatus Status { get; init; }
+
+    /// <summary>HTTP status code where applicable.</summary>
+    public int? HttpStatus { get; init; }
+
+    /// <summary>Duration of the audited action in milliseconds, when measurable.</summary>
+    public int? DurationMs { get; init; }
+
+    /// <summary>Human-readable error summary on failure rows.</summary>
+    public string? ErrorMessage { get; init; }
+
+    /// <summary>Verbose error detail (stack/exception) on failure rows.</summary>
+    public string? ErrorDetail { get; init; }
+
+    /// <summary>Truncated/redacted request summary; capped per AuditLogOptions.</summary>
+    public string? RequestSummary { get; init; }
+
+    /// <summary>Truncated/redacted response summary; capped per AuditLogOptions.</summary>
+    public string? ResponseSummary { get; init; }
+
+    /// <summary>True when Request/Response summaries were truncated to the payload cap.</summary>
+    public bool PayloadTruncated { get; init; }
+
+    /// <summary>Free-form JSON extension column for channel-specific extras.</summary>
+    public string? Extra { get; init; }
+
+    /// <summary>Site-local forwarding state; null on central rows.</summary>
+    public AuditForwardState? ForwardState { get; init; }
+}