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

/// <summary>
/// An hourly pre-aggregated KPI measurement in the central KPI-history backbone
/// ("KPI History &amp; Trends"). One row per (Source, Metric, Scope, ScopeKey)
/// per UTC hour, folded from the raw <c>KpiSample</c> rows in that hour — a
/// tall / EAV row in the central <c>KpiRollupHourly</c> table that lets long-range
/// trend queries read ~60× fewer rows than scanning raw samples.
/// </summary>
/// <remarks>
/// <para>
/// Persistence-ignorant POCO; the EF Core mapping lives in the Configuration
/// Database component. <see cref="Source"/> draws from
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiSources"/> and
/// <see cref="Scope"/> from
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes"/>; <see cref="Metric"/>
/// is drawn from each owning source's own metric catalog — the same four-tuple
/// series key as <see cref="KpiSample"/>, with identical semantics.
/// </para>
/// <para>
/// <see cref="HourStartUtc"/> is the hour-truncated UTC bucket start; the tuple
/// (<see cref="Source"/>, <see cref="Metric"/>, <see cref="Scope"/>,
/// <see cref="ScopeKey"/>, <see cref="HourStartUtc"/>) is the unique upsert key.
/// <see cref="Value"/> is the folded aggregate — a per-hour sum for rate metrics
/// or a per-hour last-value for gauge metrics (the aggregation intent lives with
/// the metric catalog). <see cref="MinValue"/>, <see cref="MaxValue"/> and
/// <see cref="SampleCount"/> preserve the fold's fidelity and unblock future
/// min/max/avg charting.
/// </para>
/// </remarks>
public sealed class KpiRollupHourly
{
    /// <summary>Surrogate identity key assigned by the store.</summary>
    public long Id { get; set; }

    /// <summary>
    /// Owning component / source — a value from
    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiSources"/>.
    /// </summary>
    public required string Source { get; set; }

    /// <summary>Metric name, drawn from the owning source's metric catalog.</summary>
    public required string Metric { get; set; }

    /// <summary>
    /// Scope discriminator — a value from
    /// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes"/>.
    /// </summary>
    public required string Scope { get; set; }

    /// <summary>
    /// Scope qualifier — the site id or node name the rollup belongs to;
    /// <c>null</c> for <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes.Global"/>.
    /// </summary>
    public string? ScopeKey { get; set; }

    /// <summary>The hour-truncated UTC start of the bucket this rollup aggregates.</summary>
    public DateTime HourStartUtc { get; set; }

    /// <summary>
    /// Folded aggregate for the hour — a sum for rate metrics, a last-value for
    /// gauge metrics. Counts are exact; ages are expressed in seconds.
    /// </summary>
    public double Value { get; set; }

    /// <summary>Minimum raw sample value observed within the hour.</summary>
    public double MinValue { get; set; }

    /// <summary>Maximum raw sample value observed within the hour.</summary>
    public double MaxValue { get; set; }

    /// <summary>Number of raw <see cref="KpiSample"/> rows folded into this hour.</summary>
    public int SampleCount { get; set; }
}
