feat(kpi): K11 — KpiHistoryQueryService (scoped read + bucketing)

src/ZB.MOM.WW.ScadaBridge.CentralUI/Services/IKpiHistoryQueryService.cs

@@ -0,0 +1,51 @@
+using ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
+
+namespace ZB.MOM.WW.ScadaBridge.CentralUI.Services;
+
+/// <summary>
+/// CentralUI facade over
+/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories.IKpiHistoryRepository"/>
+/// (M6 "KPI History &amp; Trends", K11). The reusable trend chart talks to this
+/// service rather than the repository directly so tests can substitute a fake
+/// without spinning up EF Core, and so the bucketing / downsampling step lives in
+/// one place rather than being re-implemented per page.
+/// </summary>
+/// <remarks>
+/// The query path fetches the raw series for one (source, metric, scope, scopeKey)
+/// tuple over <c>[fromUtc, toUtc]</c> and reduces it with
+/// <see cref="KpiSeriesBucketer"/> to at most <c>maxPoints</c> points. Mirroring
+/// <see cref="IAuditLogQueryService"/>, the production implementation opens its own
+/// DI scope per call so a chart's auto-load never contends with the circuit-scoped
+/// <c>ScadaBridgeDbContext</c>; a second (test-seam) constructor injects the
+/// repository directly.
+/// </remarks>
+public interface IKpiHistoryQueryService
+{
+    /// <summary>
+    /// Returns the bucketed series for one
+    /// (<paramref name="source"/>, <paramref name="metric"/>, <paramref name="scope"/>,
+    /// <paramref name="scopeKey"/>) tuple over <c>[<paramref name="fromUtc"/>,
+    /// <paramref name="toUtc"/>]</c>, reduced to at most
+    /// <paramref name="maxPoints"/> points (defaulting to
+    /// <c>KpiHistoryOptions.DefaultMaxSeriesPoints</c> when null).
+    /// </summary>
+    /// <remarks>
+    /// The window must be non-degenerate (<paramref name="toUtc"/> strictly after
+    /// <paramref name="fromUtc"/>) and the effective max must be at least 2 — the
+    /// page layer guarantees both; this service passes them straight through to
+    /// <see cref="KpiSeriesBucketer.Bucket"/>, which throws
+    /// <see cref="ArgumentOutOfRangeException"/> on violation.
+    /// </remarks>
+    /// <param name="source">Source identifier — a value from <c>KpiSources</c>.</param>
+    /// <param name="metric">Metric name from the source's catalog.</param>
+    /// <param name="scope">Scope discriminator — a value from <c>KpiScopes</c>.</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); must be after <paramref name="fromUtc"/>.</param>
+    /// <param name="maxPoints">Optional ceiling on returned points; defaults to the configured default when null.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A task resolving to the bucketed series in ascending bucket-start order.</returns>
+    Task<IReadOnlyList<KpiSeriesPoint>> GetSeriesAsync(
+        string source, string metric, string scope, string? scopeKey,
+        DateTime fromUtc, DateTime toUtc, int? maxPoints = null, CancellationToken cancellationToken = default);
+}