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

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Kpi/IKpiSampleSource.cs

@@ -0,0 +1,33 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi;
+
+namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi;
+
+/// <summary>
+/// A DI-registered provider of KPI samples (M6 "KPI History &amp; Trends"),
+/// implemented by each owning component and enumerated by the central recorder
+/// singleton at every sampling interval. The recorder stamps a single
+/// <c>capturedAtUtc</c>, fans out to every source's <see cref="CollectAsync"/>,
+/// and bulk-writes the combined samples.
+/// </summary>
+public interface IKpiSampleSource
+{
+    /// <summary>
+    /// The source this provider reports for — a value from
+    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiSources"/>. Every
+    /// <see cref="KpiSample"/> returned by <see cref="CollectAsync"/> carries this value
+    /// in <see cref="KpiSample.Source"/>.
+    /// </summary>
+    string Source { get; }
+
+    /// <summary>
+    /// Compute this source's KPIs as-of-now, stamping each returned sample's
+    /// <see cref="KpiSample.CapturedAtUtc"/> with <paramref name="capturedAtUtc"/>.
+    /// </summary>
+    /// <param name="capturedAtUtc">The shared UTC capture instant for this sampling pass.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>
+    /// A task resolving to the samples computed for this source; empty when there is
+    /// nothing to report.
+    /// </returns>
+    Task<IReadOnlyList<KpiSample>> CollectAsync(DateTime capturedAtUtc, CancellationToken cancellationToken = default);
+}

src/ZB.MOM.WW.ScadaBridge.Commons/Interfaces/Repositories/IKpiHistoryRepository.cs

@@ -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);
+}