refactor(kpi): shared public KpiMetrics catalog — source consts + UI pages key off one symbol (#178)

2026-06-19 02:04:10 -04:00
parent 47f5ca687c
commit e51104af5f
9 changed files with 135 additions and 30 deletions
@@ -0,0 +1,98 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
+
+/// <summary>
+/// Canonical <em>charted</em> KPI metric-name identifiers (M6 "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>
+/// Only the metrics a trend page actually charts are catalogued here. Sources may emit
+/// additional internal metrics (e.g. the Notification Outbox <c>stuckCount</c> /
+/// <c>oldestPendingAgeSeconds</c>, the Site Call Audit <c>deliveredLastInterval</c> /
+/// <c>stuck</c> / <c>oldestPendingAgeSeconds</c>, and the bulk of the Site Health catalog)
+/// that no page references; those stay private to their source until a page charts them.
+/// Constants are grouped by source via nested static classes mirroring
+/// <see cref="KpiSources"/>.
+/// </para>
+/// </remarks>
+public static class KpiMetrics
+{
+    /// <summary>
+    /// Charted Notification Outbox (#21) 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>Parked-row count.</summary>
+        public const string ParkedCount = "parkedCount";
+
+        /// <summary>Rows delivered in the last KPI interval.</summary>
+        public const string DeliveredLastInterval = "deliveredLastInterval";
+    }
+
+    /// <summary>
+    /// Charted Site Call Audit (#22) 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>
+    /// Charted Audit Log (#23) 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 (#11) 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>Summed store-and-forward buffer depth across all buffers.</summary>
+        public const string SfBufferDepth = "sfBufferDepth";
+    }
+}