ScadaBridge/src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Audit/SiteCallQueries.cs

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

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

/// <summary>
/// Site Calls UI -> Central: paginated, filtered query over the central
/// <c>SiteCalls</c> table (Site Call Audit #22). All filter fields are optional;
/// <see cref="StuckOnly"/> restricts results to stuck cached calls. Mirrors
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification.NotificationOutboxQueryRequest"/>
/// but uses keyset paging (<see cref="AfterCreatedAtUtc"/> + <see cref="AfterId"/>)
/// to match the repository's <c>(CreatedAtUtc DESC, TrackedOperationId DESC)</c>
/// cursor, rather than page numbers.
/// </summary>
/// <remarks>
/// <see cref="ChannelFilter"/> matches the <c>SiteCall.Channel</c> column —
/// <c>"ApiOutbound"</c> or <c>"DbOutbound"</c> (the spec's <c>Kind</c> notion;
/// the entity exposes it as <c>Channel</c>). <see cref="TargetKeyword"/> is an
/// exact-match target filter, consistent with the repository's
/// <see cref="SiteCallQueryFilter.Target"/> predicate.
/// </remarks>
/// <param name="PageSize">
/// Requested page size. The actor clamps this to the <c>[1, 200]</c> range, so
/// the effective ceiling is 200 rows per page regardless of the value sent.
/// </param>
public sealed record SiteCallQueryRequest(
    string CorrelationId,
    string? StatusFilter,
    string? SourceSiteFilter,
    string? ChannelFilter,
    string? TargetKeyword,
    bool StuckOnly,
    DateTime? FromUtc,
    DateTime? ToUtc,
    DateTime? AfterCreatedAtUtc,
    Guid? AfterId,
    int PageSize,
    string? SourceNodeFilter = null);

/// <summary>
/// A single <c>SiteCalls</c> row summarised for the Site Calls UI grid. Carries
/// only the columns the <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit.SiteCall"/>
/// entity genuinely exposes — there are no source-instance/script provenance
/// columns on that entity, so unlike
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification.NotificationSummary"/>
/// none are surfaced here.
/// </summary>
/// <remarks>
/// <see cref="HttpStatus"/> is not called out in the Site Call Audit plan, but
/// it is a real (nullable) <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit.SiteCall"/>
/// column — the last HTTP status code observed for the call — so it is surfaced
/// here for the grid; <c>null</c> for non-HTTP channels or before a first attempt.
/// </remarks>
public sealed record SiteCallSummary(
    Guid TrackedOperationId,
    string SourceSite,
    string Channel,
    string Target,
    string Status,
    int RetryCount,
    string? LastError,
    int? HttpStatus,
    DateTime CreatedAtUtc,
    DateTime UpdatedAtUtc,
    DateTime? TerminalAtUtc,
    bool IsStuck,
    string? SourceNode = null);

/// <summary>
/// Central -> Site Calls UI: paginated response for a <see cref="SiteCallQueryRequest"/>.
/// The keyset cursor of the last row is echoed back as
/// <see cref="NextAfterCreatedAtUtc"/> + <see cref="NextAfterId"/> for the caller
/// to request the following page; both are <c>null</c> when the page was empty.
/// On a repository fault <see cref="Success"/> is <c>false</c>,
/// <see cref="ErrorMessage"/> carries the cause and <see cref="SiteCalls"/> is empty.
/// </summary>
public sealed record SiteCallQueryResponse(
    string CorrelationId,
    bool Success,
    string? ErrorMessage,
    IReadOnlyList<SiteCallSummary> SiteCalls,
    DateTime? NextAfterCreatedAtUtc,
    Guid? NextAfterId);

/// <summary>
/// Site Calls UI -> Central: request for the full detail of a single cached call,
/// for the report detail modal.
/// </summary>
public sealed record SiteCallDetailRequest(
    string CorrelationId,
    Guid TrackedOperationId);

/// <summary>
/// Central -> Site Calls UI: full detail for one cached call. On a repository
/// fault or missing row, <see cref="Success"/> is <c>false</c> /
/// <see cref="Detail"/> is <c>null</c> and <see cref="ErrorMessage"/> carries
/// the cause.
/// </summary>
public sealed record SiteCallDetailResponse(
    string CorrelationId,
    bool Success,
    string? ErrorMessage,
    SiteCallDetail? Detail);

/// <summary>
/// Full <c>SiteCalls</c> row detail for the report detail modal — every field
/// on the <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Audit.SiteCall"/> entity,
/// including <see cref="LastError"/> and the <see cref="IngestedAtUtc"/>
/// timestamp the grid summary omits.
/// </summary>
public sealed record SiteCallDetail(
    Guid TrackedOperationId,
    string SourceSite,
    string Channel,
    string Target,
    string Status,
    int RetryCount,
    string? LastError,
    int? HttpStatus,
    DateTime CreatedAtUtc,
    DateTime UpdatedAtUtc,
    DateTime? TerminalAtUtc,
    DateTime IngestedAtUtc,
    string? SourceNode = null);

/// <summary>
/// Site Calls UI -> Central: request for the global <c>SiteCalls</c> KPI summary.
/// Mirrors <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification.NotificationKpiRequest"/>.
/// </summary>
public sealed record SiteCallKpiRequest(
    string CorrelationId);

/// <summary>
/// Central -> Site Calls UI: KPI summary for the Site Calls dashboard. On a
/// repository fault <see cref="Success"/> is <c>false</c>,
/// <see cref="ErrorMessage"/> carries the cause, and the KPI fields are
/// zeroed/<c>null</c>.
/// </summary>
public sealed record SiteCallKpiResponse(
    string CorrelationId,
    bool Success,
    string? ErrorMessage,
    int BufferedCount,
    int ParkedCount,
    int FailedLastInterval,
    int DeliveredLastInterval,
    TimeSpan? OldestPendingAge,
    int StuckCount);

/// <summary>
/// Site Calls UI -> Central: request for the per-source-site <c>SiteCalls</c>
/// KPI breakdown. Mirrors
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Messages.Notification.PerSiteNotificationKpiRequest"/>.
/// </summary>
public sealed record PerSiteSiteCallKpiRequest(
    string CorrelationId);

/// <summary>
/// Central -> Site Calls UI: per-site KPI breakdown for the Site Calls KPIs
/// page. On a repository fault <see cref="Success"/> is <c>false</c>,
/// <see cref="ErrorMessage"/> carries the cause, and <see cref="Sites"/> is empty.
/// </summary>
public sealed record PerSiteSiteCallKpiResponse(
    string CorrelationId,
    bool Success,
    string? ErrorMessage,
    IReadOnlyList<SiteCallSiteKpiSnapshot> Sites);

/// <summary>
/// Site Calls UI -> Central: request for the per-node <c>SiteCalls</c>
/// KPI breakdown. Mirrors <see cref="PerSiteSiteCallKpiRequest"/> but groups
/// by <c>SourceNode</c> instead of <c>SourceSite</c>. Additive — does not
/// change per-site behaviour.
/// </summary>
public sealed record PerNodeSiteCallKpiRequest(
    string CorrelationId);

/// <summary>
/// Central -> Site Calls UI: per-node KPI breakdown for the Site Calls KPIs
/// page. On a repository fault <see cref="Success"/> is <c>false</c>,
/// <see cref="ErrorMessage"/> carries the cause, and <see cref="Nodes"/> is empty.
/// Nodes with a <c>NULL</c> <c>SourceNode</c> are omitted.
/// </summary>
public sealed record PerNodeSiteCallKpiResponse(
    string CorrelationId,
    bool Success,
    string? ErrorMessage,
    IReadOnlyList<SiteCallNodeKpiSnapshot> Nodes);