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

/// <summary>
/// Operational state of one cached call as seen by the site, carried on the
/// combined <c>CachedCallTelemetry</c> packet and persisted
/// at central as the <c>SiteCalls</c> row mirroring the call's status.
/// </summary>
/// <remarks>
/// <para>
/// One row per <see cref="TrackedOperationId"/> at central; ingest is
/// insert-if-not-exists then upsert-on-newer-status (monotonic — never rolls
/// back). The site remains the source of truth — this record is the
/// "eventually-consistent mirror" the central UI's Site Calls page reads.
/// </para>
/// </remarks>
/// <param name="TrackedOperationId">Idempotency key shared with the audit row.</param>
/// <param name="Channel">
/// Trust-boundary channel — <c>"ApiOutbound"</c> or <c>"DbOutbound"</c>. String form
/// (not the <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditChannel"/> enum) so the
/// record serialises identically across SQL / gRPC / JSON boundaries.
/// </param>
/// <param name="Target">Human-readable target (e.g. <c>"ERP.GetOrder"</c>).</param>
/// <param name="SourceSite">Site id that submitted the cached call.</param>
/// <param name="SourceNode">
/// The cluster node on which the cached call was emitted — <c>node-a</c> / <c>node-b</c>
/// for site rows (qualified by <paramref name="SourceSite"/>), <c>central-a</c> /
/// <c>central-b</c> for central-originated rows. Stamped by the emitting node from
/// <c>INodeIdentityProvider</c>; nullable so reconciled rows from a node that has since
/// been retired don't block ingest.
/// </param>
/// <param name="Status">
/// Lifecycle status — string form of <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Enums.AuditStatus"/>:
/// <c>Submitted</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 dispatch attempts so far; 0 prior to first attempt.</param>
/// <param name="LastError">Most recent error message; null when no failures have occurred.</param>
/// <param name="HttpStatus">Most recent HTTP status code (API calls only); null otherwise.</param>
/// <param name="CreatedAtUtc">UTC timestamp the cached call was first submitted.</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>
public sealed record SiteCallOperational(
    TrackedOperationId TrackedOperationId,
    string Channel,
    string Target,
    string SourceSite,
    string? SourceNode,
    string Status,
    int RetryCount,
    string? LastError,
    int? HttpStatus,
    DateTime CreatedAtUtc,
    DateTime UpdatedAtUtc,
    DateTime? TerminalAtUtc);
