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

/// <summary>
/// Canonical <em>charted</em> KPI metric-name identifiers ("KPI History &amp;
/// Trends") — the value of <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi.KpiSample.Metric"/>
/// for every metric a Central UI trend chart renders. Each owning
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi.IKpiSampleSource"/> emits
/// these strings and each trend page keys its <c>GetSeriesAsync</c> lookup on the same
/// strings; promoting them to one shared public symbol means the source and the page key
/// off a single declaration, so a future rename becomes a compiler-enforced single edit
/// rather than a silently-blanked chart.
/// </summary>
/// <remarks>
/// <para>
/// Each constant's value is the metric string <em>as persisted</em> in the tall/EAV
/// <c>KpiSample</c> table and matched at query time. These values are therefore part of
/// the on-disk data contract: this catalog is a symbol-promotion of the existing literals,
/// <strong>not</strong> a rename — changing any value would orphan historical samples.
/// </para>
/// <para>
/// This catalog now carries two kinds of metric: those a trend page charts, <em>and</em>
/// those the <see cref="KpiMetricAggregationCatalog"/> classifies for the hourly rollup fold
/// (e.g. <c>SiteCallAudit/deliveredLastInterval</c>, <c>SiteHealth/alarmEvalErrors</c>,
/// <c>SiteHealth/eventLogWriteFailures</c>) even if no page charts them yet. The C4/R4 lesson
/// is that <strong>any metric named in two places needs one shared symbol</strong>: a private
/// literal on the emitter plus a matching private literal in the catalog drifts silently on a
/// rename. Sources may still keep genuinely single-use internal metrics (e.g. the Notification
/// Outbox <c>stuckCount</c> / <c>oldestPendingAgeSeconds</c>, the Site Call Audit <c>stuck</c> /
/// <c>oldestPendingAgeSeconds</c>, and the bulk of the Site Health catalog) private until a page
/// or the catalog references them.
/// Constants are grouped by source via nested static classes mirroring
/// <see cref="KpiSources"/>.
/// </para>
/// </remarks>
public static class KpiMetrics
{
    /// <summary>
    /// Charted Notification Outbox metrics — <see cref="KpiSources.NotificationOutbox"/>.
    /// Rendered by the Central UI Notification Outbox KPIs trend panel.
    /// </summary>
    public static class NotificationOutbox
    {
        /// <summary>Pending-queue depth (rows awaiting delivery).</summary>
        public const string QueueDepth = "queueDepth";

        /// <summary>Stuck-row count (non-terminal older than the stuck-age threshold).</summary>
        public const string StuckCount = "stuckCount";

        /// <summary>Parked-row count.</summary>
        public const string ParkedCount = "parkedCount";

        /// <summary>Rows delivered in the last KPI interval.</summary>
        public const string DeliveredLastInterval = "deliveredLastInterval";

        /// <summary>Age of the oldest pending row, in seconds.</summary>
        public const string OldestPendingAgeSeconds = "oldestPendingAgeSeconds";
    }

    /// <summary>
    /// Charted Site Call Audit metrics — <see cref="KpiSources.SiteCallAudit"/>.
    /// Rendered by the Central UI Site Calls report trend panel.
    /// </summary>
    public static class SiteCallAudit
    {
        /// <summary>Buffered (non-terminal) cached-call count.</summary>
        public const string Buffered = "buffered";

        /// <summary>Parked cached-call count.</summary>
        public const string Parked = "parked";

        /// <summary>Cached calls that failed permanently in the last KPI interval.</summary>
        public const string FailedLastInterval = "failedLastInterval";

        /// <summary>Cached calls delivered in the last KPI interval. Not charted by a trend
        /// page today, but named in the rollup aggregation catalog as a Rate metric — so it
        /// is a shared symbol to keep the emitter and catalog in lock-step (R4).</summary>
        public const string DeliveredLastInterval = "deliveredLastInterval";
    }

    /// <summary>
    /// Charted Audit Log metrics — <see cref="KpiSources.AuditLog"/>.
    /// Rendered by the Central UI Audit Log page trend panel.
    /// </summary>
    public static class AuditLog
    {
        /// <summary>Audit events recorded in the trailing hour.</summary>
        public const string TotalEventsLastHour = "totalEventsLastHour";

        /// <summary>Error-row audit events recorded in the trailing hour.</summary>
        public const string ErrorEventsLastHour = "errorEventsLastHour";

        /// <summary>Total pending (not-yet-forwarded) audit backlog.</summary>
        public const string BacklogTotal = "backlogTotal";
    }

    /// <summary>
    /// Charted Site Health metrics — <see cref="KpiSources.SiteHealth"/>.
    /// Rendered by the Central UI Health-dashboard per-site trend panel.
    /// </summary>
    public static class SiteHealth
    {
        /// <summary>Data connections not in the Connected state.</summary>
        public const string ConnectionsDown = "connectionsDown";

        /// <summary>Dead-letter count reported by the site.</summary>
        public const string DeadLetters = "deadLetters";

        /// <summary>Script-execution error count reported by the site.</summary>
        public const string ScriptErrors = "scriptErrors";

        /// <summary>Alarm-evaluation error count reported by the site. Named in the rollup
        /// aggregation catalog as a Rate metric — shared symbol so an emitter rename is a
        /// compile error, not a silent Gauge downgrade (R4).</summary>
        public const string AlarmEvalErrors = "alarmEvalErrors";

        /// <summary>Event-log write-failure count reported by the site. Named in the rollup
        /// aggregation catalog as a Rate metric — shared symbol so an emitter rename is a
        /// compile error, not a silent Gauge downgrade (R4).</summary>
        public const string EventLogWriteFailures = "eventLogWriteFailures";

        /// <summary>Summed store-and-forward buffer depth across all buffers.</summary>
        public const string SfBufferDepth = "sfBufferDepth";
    }
}
