feat(kpi): K1 — KpiSample + IKpiSampleSource + IKpiHistoryRepository contracts (Commons)

2026-06-17 19:35:50 -04:00
parent 4c6ae9da0e
commit 460777bffa
7 changed files with 270 additions and 0 deletions
@@ -0,0 +1,55 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi;
+
+/// <summary>
+/// A single point-in-time KPI measurement in the central KPI-history backbone
+/// (M6 "KPI History &amp; Trends"). One row per (Source, Metric, Scope, ScopeKey)
+/// captured by the recorder singleton at a sampling instant — a tall / EAV row in
+/// the central <c>KpiSample</c> table.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Persistence-ignorant POCO; the EF Core mapping lives in the Configuration
+/// Database component. <see cref="Source"/> draws from
+/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiSources"/> and
+/// <see cref="Scope"/> from
+/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes"/>; <see cref="Metric"/>
+/// is drawn from each owning source's own metric catalog.
+/// </para>
+/// <para>
+/// <see cref="Value"/> is a <see cref="double"/> that carries counts exactly and
+/// ages as seconds. <see cref="CapturedAtUtc"/> is UTC, like every timestamp in
+/// the system.
+/// </para>
+/// </remarks>
+public sealed class KpiSample
+{
+    /// <summary>Surrogate identity key assigned by the store.</summary>
+    public long Id { get; set; }
+
+    /// <summary>
+    /// Owning component / source — a value from
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiSources"/>.
+    /// </summary>
+    public required string Source { get; set; }
+
+    /// <summary>Metric name, drawn from the owning source's metric catalog.</summary>
+    public required string Metric { get; set; }
+
+    /// <summary>
+    /// Scope discriminator — a value from
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes"/>.
+    /// </summary>
+    public required string Scope { get; set; }
+
+    /// <summary>
+    /// Scope qualifier — the site id or node name the sample belongs to;
+    /// <c>null</c> for <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes.Global"/>.
+    /// </summary>
+    public string? ScopeKey { get; set; }
+
+    /// <summary>Measured value — counts are exact; ages are expressed in seconds.</summary>
+    public double Value { get; set; }
+
+    /// <summary>The UTC instant at which the sample was captured.</summary>
+    public DateTime CapturedAtUtc { get; set; }
+}