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

/// <summary>
///     Driver capability for alarm events. Optional — only drivers whose backends expose
///     alarm conditions implement this. Currently: Galaxy (MxAccess alarms), FOCAS
///     (CNC alarms), OPC UA Client (A&amp;C events from upstream server).
/// </summary>
public interface IAlarmSource
{
    /// <summary>
    ///     Subscribe to alarm events for a node-set (typically: a folder or equipment subtree).
    ///     The driver fires <see cref="OnAlarmEvent"/> for every alarm transition.
    /// </summary>
    Task<IAlarmSubscriptionHandle> SubscribeAlarmsAsync(
        IReadOnlyList<string> sourceNodeIds,
        CancellationToken cancellationToken);

    /// <summary>Cancel an alarm subscription returned by <see cref="SubscribeAlarmsAsync"/>.</summary>
    Task UnsubscribeAlarmsAsync(IAlarmSubscriptionHandle handle, CancellationToken cancellationToken);

    /// <summary>Acknowledge one or more active alarms by source node ID + condition ID.</summary>
    Task AcknowledgeAsync(
        IReadOnlyList<AlarmAcknowledgeRequest> acknowledgements,
        CancellationToken cancellationToken);

    /// <summary>Server-pushed alarm transition (raise / clear / change).</summary>
    event EventHandler<AlarmEventArgs>? OnAlarmEvent;
}

/// <summary>Opaque alarm-subscription identity returned by <see cref="IAlarmSource.SubscribeAlarmsAsync"/>.</summary>
public interface IAlarmSubscriptionHandle
{
    /// <summary>Driver-internal subscription identifier (for diagnostics + post-mortem).</summary>
    string DiagnosticId { get; }
}

/// <summary>One alarm acknowledgement in a batch.</summary>
public sealed record AlarmAcknowledgeRequest(
    string SourceNodeId,
    string ConditionId,
    string? Comment);

/// <summary>Event payload for <see cref="IAlarmSource.OnAlarmEvent"/>.</summary>
public sealed record AlarmEventArgs(
    IAlarmSubscriptionHandle SubscriptionHandle,
    string SourceNodeId,
    string ConditionId,
    string AlarmType,
    string Message,
    AlarmSeverity Severity,
    DateTime SourceTimestampUtc);

/// <summary>Mirrors the <c>NodePermissions</c> alarm-severity enum in <c>docs/v2/acl-design.md</c>.</summary>
public enum AlarmSeverity { Low, Medium, High, Critical }