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

/// <summary>
/// A single point-in-time KPI measurement in the central KPI-history backbone
/// ("KPI History &amp; Trends"). One row per (Source, Metric, Scope, ScopeKey)
/// captured by the recorder singleton at a sampling instant — a tall / EAV row in
/// the central <c>KpiSample</c> table.
/// </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.
/// </para>
/// <para>
/// <see cref="Value"/> is a <see cref="double"/> that carries counts exactly and
/// ages as seconds. <see cref="CapturedAtUtc"/> is UTC, like every timestamp in
/// the system.
/// </para>
/// </remarks>
public sealed class KpiSample
{
    /// <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 sample belongs to;
    /// <c>null</c> for <see cref="ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi.KpiScopes.Global"/>.
    /// </summary>
    public string? ScopeKey { get; set; }

    /// <summary>Measured value — counts are exact; ages are expressed in seconds.</summary>
    public double Value { get; set; }

    /// <summary>The UTC instant at which the sample was captured.</summary>
    public DateTime CapturedAtUtc { get; set; }
}
