worker(alarms): route ForcedMode/watch-list/failover via AlarmCommandHandler; emit provider-mode-changed event

src/ZB.MOM.WW.MxGateway.Worker/MxAccess/MxAccessEventMapper.cs

@@ -182,6 +182,43 @@ public sealed class MxAccessEventMapper
         return mxEvent;
     }
 
+    /// <summary>
+    ///     Creates an OnAlarmProviderModeChanged event from a
+    ///     <see cref="FailoverAlarmConsumer"/> provider switch. The worker's
+    ///     alarm path drives this when the failover composite switches between
+    ///     the alarmmgr primary and the subtag standby, so connected gateway
+    ///     clients can observe the degraded/recovered provider state.
+    /// </summary>
+    /// <param name="sessionId">Identifier of the session.</param>
+    /// <param name="mode">The provider mode now active after the switch.</param>
+    /// <param name="reason">Human-readable reason for the switch.</param>
+    /// <param name="hresult">The COM HRESULT that triggered a failover, or 0 for a clean failback.</param>
+    /// <param name="atUtc">The UTC instant the switch occurred.</param>
+    public MxEvent CreateOnAlarmProviderModeChanged(
+        string sessionId,
+        AlarmProviderMode mode,
+        string reason,
+        int hresult,
+        DateTime atUtc)
+    {
+        MxEvent mxEvent = CreateBaseEvent(
+            MxEventFamily.OnAlarmProviderModeChanged,
+            sessionId,
+            serverHandle: 0,
+            itemHandle: 0,
+            statuses: null);
+
+        mxEvent.OnAlarmProviderModeChanged = new OnAlarmProviderModeChangedEvent
+        {
+            Mode = mode,
+            Reason = reason ?? string.Empty,
+            Hresult = hresult,
+            At = Google.Protobuf.WellKnownTypes.Timestamp.FromDateTime(
+                DateTime.SpecifyKind(atUtc, DateTimeKind.Utc)),
+        };
+        return mxEvent;
+    }
+
     /// <summary>Creates an OnBufferedDataChange event from MXAccess COM event arguments.</summary>
     /// <param name="sessionId">Identifier of the session.</param>
     /// <param name="serverHandle">Handle returned by the worker.</param>