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 ("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). Implementations slice the
    /// purge into time-windowed DELETE batches so a large catch-up (e.g. after an
    /// outage) never runs as a single lock/log-heavy transaction (arch-review 04, P4).
    /// </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);
}