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,51 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi;
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
+
+/// <summary>
+/// Data access for the central KPI-history backbone (M6 "KPI History &amp; Trends")
+/// — the tall / EAV <c>KpiSample</c> table in central MS SQL. Backs the recorder
+/// singleton's bulk write, the bucketed query path that feeds the reusable trend
+/// chart, and the retention purge. Implementation lives in the Configuration
+/// Database component.
+/// </summary>
+public interface IKpiHistoryRepository
+{
+    /// <summary>
+    /// Bulk-inserts a batch of captured samples (one sampling pass across all
+    /// registered sources).
+    /// </summary>
+    /// <param name="samples">The samples to record.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task that represents the asynchronous write.</returns>
+    Task RecordSamplesAsync(IReadOnlyCollection<KpiSample> samples, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Returns the raw points for one series in <c>[fromUtc, toUtc]</c>, ordered by
+    /// <see cref="KpiSample.CapturedAtUtc"/> ascending.
+    /// </summary>
+    /// <param name="source">Source identifier — a value from <see cref="KpiSources"/>.</param>
+    /// <param name="metric">Metric name from the source's catalog.</param>
+    /// <param name="scope">Scope discriminator — a value from <see cref="KpiScopes"/>.</param>
+    /// <param name="scopeKey">Scope qualifier (site id / node name); <c>null</c> for the Global scope.</param>
+    /// <param name="fromUtc">Inclusive lower bound of the time window (UTC).</param>
+    /// <param name="toUtc">Inclusive upper bound of the time window (UTC).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>
+    /// A task resolving to the raw series points in ascending capture order; empty when
+    /// the series has no samples in the window.
+    /// </returns>
+    Task<IReadOnlyList<KpiSeriesPoint>> GetRawSeriesAsync(
+        string source, string metric, string scope, string? scopeKey,
+        DateTime fromUtc, DateTime toUtc, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Bulk-deletes rows whose <see cref="KpiSample.CapturedAtUtc"/> is strictly older
+    /// than <paramref name="before"/> (retention purge).
+    /// </summary>
+    /// <param name="before">UTC cut-off; rows captured before this instant are deleted.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to the number of rows deleted.</returns>
+    Task<int> PurgeOlderThanAsync(DateTime before, CancellationToken cancellationToken = default);
+}