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

/// <summary>
/// Outcome of a Site Call Audit Retry/Discard relay — distinguishes the
/// three cases the Central UI Site Calls page must surface differently.
/// </summary>
/// <remarks>
/// The "site unreachable" case is deliberately separate from
/// <see cref="OperationFailed"/>: central is an eventually-consistent mirror,
/// not the source of truth, so a relay that never reaches the owning site is a
/// transient transport condition the operator can retry — not a failed
/// operation. The UI shows "site unreachable" rather than a generic error.
/// </remarks>
public enum SiteCallRelayOutcome
{
    /// <summary>
    /// The owning site received the relay command and applied the action to its
    /// Store-and-Forward buffer (the parked cached call was reset to retry, or
    /// discarded). The corrected state reaches central later via telemetry.
    /// </summary>
    Applied,

    /// <summary>
    /// The owning site received the relay command but found nothing to do — no
    /// parked row matched the tracked id (already delivered/discarded, or no
    /// longer <c>Parked</c>). A definitive answer from the site, not a failure.
    /// </summary>
    NotParked,

    /// <summary>
    /// The owning site could not be reached (offline / no route to the site /
    /// relay timed out). The action was NOT applied; the operator may retry once
    /// the site is back online.
    /// </summary>
    SiteUnreachable,

    /// <summary>
    /// The owning site was reached but reported it could not apply the action
    /// (its parked-message handler was unavailable or its store faulted).
    /// </summary>
    OperationFailed,
}

/// <summary>
/// Central UI → Site Call Audit: relay a Retry of a parked cached call to its
/// owning site. The owning site performs the actual retry on its
/// Store-and-Forward buffer — central never mutates the central <c>SiteCalls</c>
/// mirror row. Mirrors
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification.RetryNotificationRequest"/>
/// but carries <see cref="SourceSite"/> (the relay target) and answers with a
/// distinct site-unreachable outcome.
/// </summary>
/// <param name="CorrelationId">Request correlation id, echoed on the response.</param>
/// <param name="TrackedOperationId">
/// The cached operation to retry — the PK of the central <c>SiteCalls</c> row
/// and the S&amp;F buffer message id at the owning site.
/// </param>
/// <param name="SourceSite">
/// The owning site (<c>SiteCall.SourceSite</c>) the relay is routed to.
/// </param>
/// <param name="RequestedBy">
/// The authenticated operator who initiated the retry, stamped as the <c>Actor</c>
/// on the central direct-write audit row the relay emits — recording *who asked*.
/// Additive; null where no identity is available.
/// </param>
public sealed record RetrySiteCallRequest(
    string CorrelationId,
    Guid TrackedOperationId,
    string SourceSite,
    string? RequestedBy = null);

/// <summary>
/// Site Call Audit → Central UI: result of a <see cref="RetrySiteCallRequest"/>.
/// </summary>
/// <param name="CorrelationId">Echoed request correlation id.</param>
/// <param name="Outcome">
/// The relay outcome — <see cref="SiteCallRelayOutcome.Applied"/>,
/// <see cref="SiteCallRelayOutcome.NotParked"/>,
/// <see cref="SiteCallRelayOutcome.SiteUnreachable"/> or
/// <see cref="SiteCallRelayOutcome.OperationFailed"/>.
/// </param>
/// <param name="Success">
/// Convenience flag — <c>true</c> only for <see cref="SiteCallRelayOutcome.Applied"/>.
/// </param>
/// <param name="SiteReachable">
/// <c>false</c> only for <see cref="SiteCallRelayOutcome.SiteUnreachable"/>; lets
/// the UI distinguish "site offline" from "operation failed" without switching
/// on the enum.
/// </param>
/// <param name="ErrorMessage">
/// Human-readable detail for a non-applied outcome; <c>null</c> on success.
/// </param>
public sealed record RetrySiteCallResponse(
    string CorrelationId,
    SiteCallRelayOutcome Outcome,
    bool Success,
    bool SiteReachable,
    string? ErrorMessage);

/// <summary>
/// Central UI → Site Call Audit: relay a Discard of a parked cached call to its
/// owning site. See <see cref="RetrySiteCallRequest"/> for the source-of-truth
/// and routing rationale.
/// </summary>
public sealed record DiscardSiteCallRequest(
    string CorrelationId,
    Guid TrackedOperationId,
    string SourceSite,
    string? RequestedBy = null);

/// <summary>
/// Site Call Audit → Central UI: result of a <see cref="DiscardSiteCallRequest"/>.
/// Same shape as <see cref="RetrySiteCallResponse"/>.
/// </summary>
public sealed record DiscardSiteCallResponse(
    string CorrelationId,
    SiteCallRelayOutcome Outcome,
    bool Success,
    bool SiteReachable,
    string? ErrorMessage);