using ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi;

/// <summary>
/// A DI-registered provider of KPI samples ("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);
}
