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

/// <summary>
/// How a KPI metric must be folded when an hour of one-minute
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi.KpiSample"/> rows is
/// aggregated into a single <c>KpiRollupHourly</c> row ("KPI History &amp; Trends"
/// hourly rollups, deferred #22). The correct fold differs by metric semantics, and
/// choosing the wrong one silently corrupts long-range trend charts.
/// </summary>
public enum KpiRollupAggregation
{
    /// <summary>
    /// An instantaneous gauge (e.g. queue depth, buffered count, oldest-pending age).
    /// The faithful hourly fold is <strong>last-value-per-hour</strong> — a gauge has
    /// no meaningful sum across the 60 one-minute samples in an hour; summing would
    /// invent a nonsensical total, whereas the latest reading is the value that a live
    /// tile would have shown at the hour boundary.
    /// </summary>
    Gauge = 0,

    /// <summary>
    /// An already-windowed rate / delta counter (e.g. delivered-last-interval,
    /// per-interval error counts). The faithful hourly fold is
    /// <strong>sum-per-hour</strong> — each minute's sample is a fresh count of what
    /// happened in that interval, so the hour's true total is the sum of its samples.
    /// Folding a rate as last-value would keep one minute's delta and discard the other
    /// 59, silently under-counting every long-range total.
    /// </summary>
    Rate = 1,
}

/// <summary>
/// Authoritative classification of every KPI metric emitted by the four
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi.IKpiSampleSource"/>
/// implementations as a <see cref="KpiRollupAggregation.Gauge"/> or a
/// <see cref="KpiRollupAggregation.Rate"/>, keyed by the <c>(source, metric)</c>
/// pair. The hourly rollup fold consults this to pick last-value-per-hour vs.
/// sum-per-hour for each series.
/// </summary>
/// <remarks>
/// <para>
/// Keying by <c>(source, metric)</c> — not metric alone — is deliberate:
/// <c>deliveredLastInterval</c> is emitted by both
/// <see cref="KpiSources.NotificationOutbox"/> and <see cref="KpiSources.SiteCallAudit"/>,
/// so a metric name is not globally unique. Every catalogued metric string is now a shared
/// <see cref="KpiMetrics"/> constant — the emitting source consumes the same constant — so an
/// emitter rename is a <strong>compile error</strong>, not a silent Gauge downgrade (R4), and
/// this catalog stays a faithful mirror of what actually lands in <c>KpiSample.Metric</c>.
/// </para>
/// <para>
/// The catalog stores only the <see cref="KpiRollupAggregation.Rate"/> pairs; anything
/// not listed — including an unknown, newly-added metric — resolves to
/// <see cref="KpiRollupAggregation.Gauge"/>. Gauge is the safe default: last-value-per-hour
/// never fabricates a total, so a metric that slips in without being classified degrades
/// to a plausible reading rather than crashing the fold or silently multiplying a count.
/// </para>
/// </remarks>
public static class KpiMetricAggregationCatalog
{
    /// <summary>
    /// The <c>(source, metric)</c> pairs classified as <see cref="KpiRollupAggregation.Rate"/>
    /// (sum-per-hour). Every other emitted metric is a <see cref="KpiRollupAggregation.Gauge"/>.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Rate members are per-interval / per-report deltas whose hour total is the sum of
    /// its minute samples:
    /// <list type="bullet">
    ///   <item><c>NotificationOutbox/deliveredLastInterval</c> — rows delivered in the last KPI interval.</item>
    ///   <item><c>SiteCallAudit/failedLastInterval</c> — cached calls that failed permanently in the last KPI interval.</item>
    ///   <item><c>SiteCallAudit/deliveredLastInterval</c> — cached calls delivered in the last KPI interval.</item>
    ///   <item><c>SiteHealth/scriptErrors</c>, <c>SiteHealth/alarmEvalErrors</c>,
    ///     <c>SiteHealth/deadLetters</c>, <c>SiteHealth/eventLogWriteFailures</c> — raw error
    ///     counts <em>per health-report interval</em> (site health reports carry raw counts per
    ///     interval, not running totals), so they accumulate over the hour.</item>
    /// </list>
    /// </para>
    /// <para>
    /// <strong>Deliberately NOT Rate — the <c>*LastHour</c> audit metrics are Gauges.</strong>
    /// <c>AuditLog/totalEventsLastHour</c> and <c>AuditLog/errorEventsLastHour</c> read as
    /// "rate-like" by name, but <see cref="ZB.MOM.WW.ScadaBridge.AuditLog"/>'s sample source
    /// computes each as a <em>rolling trailing-one-hour</em> count (a fixed 1-hour window,
    /// re-evaluated at every capture). Each minute's value therefore already <em>is</em> the
    /// last-hour total, and consecutive minutes overlap by 59 minutes. Summing the 60 samples
    /// in an hour would count each event dozens of times (~60× over-count). The correct fold is
    /// last-value-per-hour: at the hour boundary the latest rolling-hour count closely tracks
    /// the hour's own volume, exactly like every other gauge. So both stay
    /// <see cref="KpiRollupAggregation.Gauge"/>, overriding the tentative plan list per the
    /// authoritative source semantics.
    /// </para>
    /// </remarks>
    private static readonly HashSet<(string Source, string Metric)> RatePairs = new()
    {
        (KpiSources.NotificationOutbox, KpiMetrics.NotificationOutbox.DeliveredLastInterval),
        (KpiSources.SiteCallAudit, KpiMetrics.SiteCallAudit.FailedLastInterval),
        (KpiSources.SiteCallAudit, KpiMetrics.SiteCallAudit.DeliveredLastInterval),
        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.ScriptErrors),
        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.AlarmEvalErrors),
        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.DeadLetters),
        (KpiSources.SiteHealth, KpiMetrics.SiteHealth.EventLogWriteFailures),
    };

    /// <summary>
    /// Resolves how the metric identified by <paramref name="source"/> +
    /// <paramref name="metric"/> must be folded into an hourly rollup.
    /// </summary>
    /// <param name="source">The emitting KPI source (a <see cref="KpiSources"/> value).</param>
    /// <param name="metric">The metric name as persisted in <c>KpiSample.Metric</c>.</param>
    /// <returns>
    /// <see cref="KpiRollupAggregation.Rate"/> for a known per-interval counter;
    /// <see cref="KpiRollupAggregation.Gauge"/> for every known gauge <em>and</em> for any
    /// unknown / newly-added <c>(source, metric)</c> pair. Never throws — the fold must not
    /// crash on a metric added after this catalog was last updated.
    /// </returns>
    public static KpiRollupAggregation Resolve(string source, string metric) =>
        RatePairs.Contains((source, metric))
            ? KpiRollupAggregation.Rate
            : KpiRollupAggregation.Gauge;
}
