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

/// <summary>
/// Site-local snapshot of a cached operation's tracking state, returned by the
/// <c>Tracking.Status(TrackedOperationId)</c> script API.
/// </summary>
/// <param name="Id">Tracking handle returned by <c>CachedCall</c>/<c>CachedWrite</c>.</param>
/// <param name="Kind">
/// Operation category — <c>"ApiCallCached"</c> or <c>"DbWriteCached"</c> — mirroring
/// the <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditKind"/> per-attempt vocabulary.
/// </param>
/// <param name="TargetSummary">
/// Human-readable target (e.g. <c>"ERP.GetOrder"</c> or <c>"WarehouseDb"</c>); may be
/// null for early-lifecycle rows recorded before the target was resolved.
/// </param>
/// <param name="Status">
/// Lifecycle status — one of <c>Submitted</c>, <c>Forwarded</c>, <c>Retrying</c>,
/// <c>Attempted</c>, <c>Delivered</c>, <c>Failed</c>, <c>Parked</c>, <c>Discarded</c>.
/// </param>
/// <param name="RetryCount">Number of attempts made; 0 prior to first dispatch.</param>
/// <param name="LastError">Most recent error message; null while non-terminal-and-no-failures.</param>
/// <param name="HttpStatus">Most recent HTTP status code where applicable; null otherwise.</param>
/// <param name="CreatedAtUtc">UTC timestamp the tracking row was first recorded.</param>
/// <param name="UpdatedAtUtc">UTC timestamp of the latest status mutation.</param>
/// <param name="TerminalAtUtc">UTC timestamp the row reached a terminal status; null while still active.</param>
/// <param name="SourceInstanceId">Instance id that issued the cached call, when known.</param>
/// <param name="SourceScript">Script that issued the cached call, when known.</param>
/// <param name="SourceNode">
/// Cluster node that submitted the cached call (e.g. <c>"node-a"</c> /
/// <c>"node-b"</c>), captured at enqueue time. Null on rows persisted before
/// the SourceNode stamping migration; stamping itself is wired in a later task.
/// Trailing-optional with a <c>= null</c> default, matching the
/// SourceNode rollout convention now used on <c>SiteCallSummary</c>,
/// <c>SiteCallDetail</c>, <c>NotificationSummary</c> and <c>NotificationDetail</c>
/// — so existing positional construction sites keep compiling as new
/// optional fields land on this record.
/// </param>
public sealed record TrackingStatusSnapshot(
    TrackedOperationId Id,
    string Kind,
    string? TargetSummary,
    string Status,
    int RetryCount,
    string? LastError,
    int? HttpStatus,
    DateTime CreatedAtUtc,
    DateTime UpdatedAtUtc,
    DateTime? TerminalAtUtc,
    string? SourceInstanceId,
    string? SourceScript,
    string? SourceNode = null);
