using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;

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

/// <summary>
/// Protocol-neutral alarm transition emitted by an
/// <c>IAlarmSubscribableConnection</c> adapter (OPC UA A&amp;C or MxGateway).
/// Keyed by <see cref="SourceReference"/>; routed to instances by
/// <see cref="SourceObjectReference"/>.
/// </summary>
/// <param name="SourceReference">Stable per-condition key (e.g. "Tank01.Level.HiHi").</param>
/// <param name="SourceObjectReference">Owning source object used for instance routing (e.g. "Tank01").</param>
/// <param name="AlarmTypeName">Source alarm type (e.g. "AnalogLimitAlarm.HiHi").</param>
/// <param name="Kind">Transition classification, incl. snapshot replay sentinels.</param>
/// <param name="Condition">Mirrored condition state.</param>
/// <param name="Category">Source taxonomy/category.</param>
/// <param name="Description">Human-readable description from the source template.</param>
/// <param name="Message">Event message text.</param>
/// <param name="OperatorUser">Operator principal on ack transitions (display-only).</param>
/// <param name="OperatorComment">Operator comment on ack transitions (display-only).</param>
/// <param name="OriginalRaiseTime">When the condition originally became active, if known.</param>
/// <param name="TransitionTime">When this transition occurred.</param>
/// <param name="CurrentValue">Current source value (display-only).</param>
/// <param name="LimitValue">Limit/threshold value for limit alarms (display-only).</param>
/// <param name="AckTime">
/// When the condition was acknowledged, or <c>null</c> while it is unacknowledged.
/// Additive trailing parameter (MES alarm-status API §6.4) so every existing positional
/// construction stays valid. Stamped by the adapter: the SOURCE's own ack instant where the
/// protocol supplies one (OPC UA A&amp;C <c>AckedState/TransitionTime</c>), otherwise the
/// transition time the DCL OBSERVED the ack at (MxAccess Gateway). Non-null only while the
/// condition is active AND acknowledged, so a re-raise (which arrives unacknowledged) clears it.
/// </param>
public record NativeAlarmTransition(
    string SourceReference,
    string SourceObjectReference,
    string AlarmTypeName,
    AlarmTransitionKind Kind,
    AlarmConditionState Condition,
    string Category,
    string Description,
    string Message,
    string OperatorUser,
    string OperatorComment,
    DateTimeOffset? OriginalRaiseTime,
    DateTimeOffset TransitionTime,
    string CurrentValue,
    string LimitValue,
    DateTimeOffset? AckTime = null);
