namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;

/// <summary>
/// ScadaBridge domain fields that travel inside <c>ZB.MOM.WW.Audit.AuditEvent.DetailsJson</c>.
/// All optional. <c>Channel</c>, <c>Kind</c>, and <c>Status</c> carry the string
/// representations of the corresponding ScadaBridge enums for stable JSON serialization.
/// <c>ForwardState</c> is deliberately absent — it remains a site-sidecar concern.
/// Serialized and deserialized by <see cref="AuditDetailsCodec"/>.
/// Property declaration order is load-bearing: <see cref="AuditDetailsCodec"/> relies on it for
/// byte-deterministic output (System.Text.Json respects declared order).
/// </summary>
/// <remarks>
/// Pure types only.
/// </remarks>
public sealed record AuditDetails
{
    /// <summary>Top-level audit channel (<c>AuditChannel.ToString()</c>).</summary>
    public string? Channel { get; init; }

    /// <summary>Specific event kind (<c>AuditKind.ToString()</c>).</summary>
    public string? Kind { get; init; }

    /// <summary>Lifecycle status (<c>AuditStatus.ToString()</c>).</summary>
    public string? Status { get; init; }

    /// <summary>Execution / operation identifier for the audited call.</summary>
    public Guid? ExecutionId { get; init; }

    /// <summary>Parent execution identifier for nested / cached operations.</summary>
    public Guid? ParentExecutionId { get; init; }

    /// <summary>Site identifier where the event originated.</summary>
    public string? SourceSiteId { get; init; }

    /// <summary>Instance (Galaxy instance / target resource) identifier.</summary>
    public string? SourceInstanceId { get; init; }

    /// <summary>Script name or endpoint that initiated the audited action.</summary>
    public string? SourceScript { get; init; }

    /// <summary>HTTP status code returned by the outbound or inbound call.</summary>
    public int? HttpStatus { get; init; }

    /// <summary>Elapsed duration of the audited action in milliseconds.</summary>
    public int? DurationMs { get; init; }

    /// <summary>Short error message when the action failed.</summary>
    public string? ErrorMessage { get; init; }

    /// <summary>Full error detail / stack excerpt when the action failed.</summary>
    public string? ErrorDetail { get; init; }

    /// <summary>Condensed request representation (URL, method, or payload summary).</summary>
    public string? RequestSummary { get; init; }

    /// <summary>Condensed response representation (status + body summary).</summary>
    public string? ResponseSummary { get; init; }

    /// <summary>
    /// <c>true</c> if any string field in this record was truncated before serialization.
    /// Included in JSON even when <c>false</c> (non-nullable bool, never null-omitted).
    /// </summary>
    public bool PayloadTruncated { get; init; }

    /// <summary>Freeform extension JSON for fields not covered above.</summary>
    public string? Extra { get; init; }

    /// <summary>UTC instant when the central AuditLog store ingested this event.</summary>
    public DateTimeOffset? IngestedAtUtc { get; init; }
}
