feat(kpihistory): add KpiRollupHourly table + EF config + migration (plan #22 T1)

New KpiRollupHourly entity is the hourly pre-aggregated series backbone folded from raw KpiSample rows, letting long-range (30d/90d) trend reads scan ~60x fewer rows. Same (Source, Metric, Scope, ScopeKey) series key as KpiSample plus HourStartUtc bucket, folded Value, and MinValue/MaxValue/SampleCount fidelity columns. UNIQUE IX_KpiRollupHourly_Series (upsert key + range-read cover, with the default [ScopeKey] IS NOT NULL filter suppressed so Global rows participate) and IX_KpiRollupHourly_Hour for purge. Non-partitioned, [PRIMARY], no DB-role restriction. Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
2026-07-10 11:41:58 -04:00
parent 84112db344
commit 0f5e70fd35
6 changed files with 2344 additions and 0 deletions
@@ -0,0 +1,74 @@
+namespace ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi;
+
+/// <summary>
+/// An hourly pre-aggregated KPI measurement in the central KPI-history backbone
+/// ("KPI History &amp; Trends"). One row per (Source, Metric, Scope, ScopeKey)
+/// per UTC hour, folded from the raw <c>KpiSample</c> rows in that hour — a
+/// tall / EAV row in the central <c>KpiRollupHourly</c> table that lets long-range
+/// trend queries read ~60× fewer rows than scanning raw samples.
+/// </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 — the same four-tuple
+/// series key as <see cref="KpiSample"/>, with identical semantics.
+/// </para>
+/// <para>
+/// <see cref="HourStartUtc"/> is the hour-truncated UTC bucket start; the tuple
+/// (<see cref="Source"/>, <see cref="Metric"/>, <see cref="Scope"/>,
+/// <see cref="ScopeKey"/>, <see cref="HourStartUtc"/>) is the unique upsert key.
+/// <see cref="Value"/> is the folded aggregate — a per-hour sum for rate metrics
+/// or a per-hour last-value for gauge metrics (the aggregation intent lives with
+/// the metric catalog). <see cref="MinValue"/>, <see cref="MaxValue"/> and
+/// <see cref="SampleCount"/> preserve the fold's fidelity and unblock future
+/// min/max/avg charting.
+/// </para>
+/// </remarks>
+public sealed class KpiRollupHourly
+{
+    /// <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 rollup belongs to;
+    /// <c>null</c> for <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes.Global"/>.
+    /// </summary>
+    public string? ScopeKey { get; set; }
+
+    /// <summary>The hour-truncated UTC start of the bucket this rollup aggregates.</summary>
+    public DateTime HourStartUtc { get; set; }
+
+    /// <summary>
+    /// Folded aggregate for the hour — a sum for rate metrics, a last-value for
+    /// gauge metrics. Counts are exact; ages are expressed in seconds.
+    /// </summary>
+    public double Value { get; set; }
+
+    /// <summary>Minimum raw sample value observed within the hour.</summary>
+    public double MinValue { get; set; }
+
+    /// <summary>Maximum raw sample value observed within the hour.</summary>
+    public double MaxValue { get; set; }
+
+    /// <summary>Number of raw <see cref="KpiSample"/> rows folded into this hour.</summary>
+    public int SampleCount { get; set; }
+}