namespace ZB.MOM.WW.OtOpcUa.Core.Abstractions;

/// <summary>
///     Health snapshot a driver returns to the Core. Drives the status dashboard,
///     ServiceLevel computation, and Bad-quality fan-out decisions.
/// </summary>
/// <param name="State">Current driver-instance state.</param>
/// <param name="LastSuccessfulRead">Timestamp of the most recent successful equipment read; null if never.</param>
/// <param name="LastError">
///     Most recent error message; null when no error has been recorded. The type makes no
///     guarantee about correlation with <paramref name="State"/> — a driver in
///     <see cref="DriverState.Healthy"/> may legitimately retain the last error from a recovered
///     failure (useful for diagnostics), and <see cref="DriverState.Degraded"/> /
///     <see cref="DriverState.Reconnecting"/> / <see cref="DriverState.Faulted"/> states may all
///     carry a non-null message. Callers must not key behaviour on the LastError-null ↔ Healthy
///     pairing (Core.Abstractions-008).
/// </param>
public sealed record DriverHealth(
    DriverState State,
    DateTime? LastSuccessfulRead,
    string? LastError);

/// <summary>Driver-instance lifecycle state.</summary>
public enum DriverState
{
    /// <summary>Driver has not been initialized yet.</summary>
    Unknown,

    /// <summary>Driver is in the middle of <see cref="IDriver.InitializeAsync"/> or <see cref="IDriver.ReinitializeAsync"/>.</summary>
    Initializing,

    /// <summary>Driver is connected and serving data.</summary>
    Healthy,

    /// <summary>Driver is connected but reporting degraded data (e.g. some equipment unreachable, some tags Bad).</summary>
    Degraded,

    /// <summary>Driver lost connection to its data source; reconnecting in the background.</summary>
    Reconnecting,

    /// <summary>
    ///     Driver hit an unrecoverable error and stopped trying.
    ///     Operator must reinitialize via Admin UI; nodes report Bad quality.
    /// </summary>
    Faulted,
}