Files
mxaccessgw/src/ZB.MOM.WW.MxGateway.Worker/MxAccess/AlarmRecordTransitionMapper.cs
T
Joseph Doherty 892bdc1a19
ci / nightly-windev (push) Has been skipped
ci / windows-x86 (push) Successful in 1m26s
ci / java (push) Successful in 2m28s
ci / portable (push) Failing after 3m38s
fix(worker): wnwrap alarm DATE+TIME are UTC; stop re-applying GMTOFFSET (#226)
QueryActiveAlarms / alarm transitions reported every wnwrap alarm late by
the record's GMTOFFSET-DSTADJUST: ParseTransitionTimestampUtc treated the
XML DATE+TIME as producer-local and added the offset, but the fields are
already UTC. DEV evidence: RuntimeAlert raise EventTimeUtc 2026-07-28
20:02:46.830 (EventTimeUTCOffsetMins -300) surfaced as 2026-07-29
01:02:46.830Z. The 2026-05-01 probe capture (TIME 13:26:14.709,
GMTOFFSET 240) was committed at 09:44 EDT, so its TIME is UTC too.

GMTOFFSET/DSTADJUST are no longer read. Tests updated + #226 regressions.
2026-11-12 07:20:44 -05:00

214 lines
10 KiB
C#

using System;
using ZB.MOM.WW.MxGateway.Contracts.Proto;
namespace ZB.MOM.WW.MxGateway.Worker.MxAccess;
/// <summary>
/// Translation helpers between the wnwrapConsumer XML payload and the
/// proto-friendly <see cref="AlarmTransitionKind"/> wire format, plus
/// alarm-reference composition.
/// </summary>
/// <remarks>
/// <para>
/// These mappings stay pure and library-agnostic so they're unit
/// testable without an AVEVA install. The COM-side I/O lives on
/// <see cref="WnWrapAlarmConsumer"/>.
/// </para>
/// </remarks>
public static class AlarmRecordTransitionMapper
{
/// <summary>
/// Decode AVEVA's STATE string (one of <c>UNACK_ALM</c>, <c>ACK_ALM</c>,
/// <c>UNACK_RTN</c>, <c>ACK_RTN</c>) into the worker's library-agnostic
/// <see cref="MxAlarmStateKind"/>. Unknown values map to
/// <see cref="MxAlarmStateKind.Unspecified"/>.
/// </summary>
/// <param name="stateXml">The state XML string from AVEVA (e.g., UNACK_ALM, ACK_RTN).</param>
/// <returns>The parsed <see cref="MxAlarmStateKind"/>, or <see cref="MxAlarmStateKind.Unspecified"/> when unrecognized.</returns>
public static MxAlarmStateKind ParseStateKind(string? stateXml)
{
if (string.IsNullOrWhiteSpace(stateXml)) return MxAlarmStateKind.Unspecified;
return stateXml!.Trim().ToUpperInvariant() switch
{
"UNACK_ALM" => MxAlarmStateKind.UnackAlm,
"ACK_ALM" => MxAlarmStateKind.AckAlm,
"UNACK_RTN" => MxAlarmStateKind.UnackRtn,
"ACK_RTN" => MxAlarmStateKind.AckRtn,
_ => MxAlarmStateKind.Unspecified,
};
}
/// <summary>
/// Decide which proto transition kind a state change represents.
/// The decision table:
/// <list type="bullet">
/// <item><description><c>previous=Unspecified</c> + <c>current=*Alm</c> → Raise (new alarm).</description></item>
/// <item><description><c>previous=Unspecified</c> + <c>current=*Rtn</c> → Clear (alarm appeared in cleared state — rare; missed the raise).</description></item>
/// <item><description><c>previous=Unack*</c> + <c>current=Ack*</c> → Acknowledge.</description></item>
/// <item><description><c>previous=*Alm</c> + <c>current=*Rtn</c> → Clear.</description></item>
/// <item><description><c>previous=*Rtn</c> + <c>current=*Alm</c> → Raise (re-trigger after clear).</description></item>
/// <item><description>Anything else → Unspecified (no proto kind to emit).</description></item>
/// </list>
/// <para>
/// <see cref="AlarmTransitionKind.Retrigger"/> is never returned. It is
/// reserved in the contract, but neither alarm source gives the worker
/// a native re-alarm signal: the alarmmgr XML carries only the four
/// <c>*_ALM</c>/<c>*_RTN</c> states, so a return-to-alarm is
/// indistinguishable from a fresh raise and is reported as Raise, and
/// the subtag source observes no re-alarm counter. Deliberately not
/// synthesized (the gateway forwards only transitions the source
/// reports — see docs/AlarmClientDiscovery.md, "Retrigger
/// transitions").
/// </para>
/// </summary>
/// <param name="previous">The previous alarm state kind.</param>
/// <param name="current">The current alarm state kind.</param>
/// <returns>The proto <see cref="AlarmTransitionKind"/> that the state change represents.</returns>
public static AlarmTransitionKind MapTransition(
MxAlarmStateKind previous,
MxAlarmStateKind current)
{
if (current == MxAlarmStateKind.Unspecified) return AlarmTransitionKind.Unspecified;
bool currentIsAlm = current is MxAlarmStateKind.UnackAlm or MxAlarmStateKind.AckAlm;
bool currentIsRtn = current is MxAlarmStateKind.UnackRtn or MxAlarmStateKind.AckRtn;
bool currentIsAcked = current is MxAlarmStateKind.AckAlm or MxAlarmStateKind.AckRtn;
if (previous == MxAlarmStateKind.Unspecified)
{
return currentIsAlm ? AlarmTransitionKind.Raise : AlarmTransitionKind.Clear;
}
bool previousIsAlm = previous is MxAlarmStateKind.UnackAlm or MxAlarmStateKind.AckAlm;
bool previousIsRtn = previous is MxAlarmStateKind.UnackRtn or MxAlarmStateKind.AckRtn;
bool previousIsAcked = previous is MxAlarmStateKind.AckAlm or MxAlarmStateKind.AckRtn;
if (previousIsAlm && currentIsRtn) return AlarmTransitionKind.Clear;
if (previousIsRtn && currentIsAlm) return AlarmTransitionKind.Raise;
if (!previousIsAcked && currentIsAcked) return AlarmTransitionKind.Acknowledge;
return AlarmTransitionKind.Unspecified;
}
/// <summary>
/// Compose <c>alarm_full_reference</c> as <c>Provider!Group.AlarmName</c>.
/// The format mirrors AVEVA's standard alarm-reference syntax so
/// downstream consumers that already speak it (e.g. the gateway's
/// AcknowledgeAlarm RPC echoing a reference back as a GUID lookup)
/// don't need translation.
/// </summary>
/// <param name="providerName">The provider name, or null.</param>
/// <param name="groupName">The group name, or null.</param>
/// <param name="alarmName">The alarm name, or null.</param>
/// <returns>The composed <c>Provider!Group.AlarmName</c> reference string.</returns>
public static string ComposeFullReference(string? providerName, string? groupName, string? alarmName)
{
string provider = providerName ?? string.Empty;
string group = groupName ?? string.Empty;
string name = alarmName ?? string.Empty;
if (string.IsNullOrEmpty(provider))
{
return string.IsNullOrEmpty(group) ? name : $"{group}.{name}";
}
return string.IsNullOrEmpty(group)
? $"{provider}!{name}"
: $"{provider}!{group}.{name}";
}
/// <summary>
/// Reassemble the UTC <see cref="DateTime"/> carried by the wnwrap
/// XML's <c>DATE</c> + <c>TIME</c> fields. Returns
/// <see cref="DateTime.MinValue"/> when DATE / TIME can't be parsed
/// (best-effort — failure is non-fatal; the proto will carry the epoch
/// and the EventQueue's fault counter records the parse miss).
/// </summary>
/// <remarks>
/// <para>
/// <c>DATE</c> + <c>TIME</c> are already UTC. The sibling
/// <c>GMTOFFSET</c> / <c>DSTADJUST</c> fields describe the
/// producer's local zone (informational only) and must NOT be
/// applied again — doing so shifted every alarm timestamp late by
/// the producer's offset (mxaccessgw#226: +5 h on DEV for a record
/// carrying <c>GMTOFFSET=300</c>, +4 h for the usual <c>240</c>).
/// </para>
/// <para>
/// Evidence: the 2026-05-01 dev-rig capture (<c>TIME 13:26:14.709</c>,
/// <c>GMTOFFSET=240</c>) was committed at 09:44 EDT that morning, so
/// 13:26 can only be UTC (09:26 EDT); and on wonder-sql-vd03 the
/// <c>CVDAisle_1.TableAlarms_008.RuntimeAlert</c> raise is
/// <c>EventTimeUtc 2026-07-28 20:02:46.830</c> with
/// <c>EventTimeUTCOffsetMins -300</c>, which the old
/// "local + offset" rule turned into <c>2026-07-29 01:02:46.830Z</c>.
/// </para>
/// </remarks>
/// <param name="xmlDate">e.g. <c>"2026/5/1"</c> (no zero-padding).</param>
/// <param name="xmlTime">e.g. <c>"13:26:14.709"</c> (UTC).</param>
/// <returns>The UTC timestamp, or <see cref="DateTime.MinValue"/> when parsing fails.</returns>
public static DateTime ParseTransitionTimestampUtc(
string? xmlDate,
string? xmlTime)
{
if (string.IsNullOrWhiteSpace(xmlDate) || string.IsNullOrWhiteSpace(xmlTime))
{
return DateTime.MinValue;
}
// Parse DATE: yyyy/M/d (no zero padding observed). Use ParseExact with
// multiple format candidates — AVEVA's locale may format differently
// on non-en-US hosts.
string[] dateFormats =
{
"yyyy/M/d", "yyyy/MM/dd", "M/d/yyyy", "MM/dd/yyyy",
"d/M/yyyy", "dd/MM/yyyy",
};
string dateTrim = xmlDate!.Trim();
if (!DateTime.TryParseExact(
dateTrim,
dateFormats,
System.Globalization.CultureInfo.InvariantCulture,
System.Globalization.DateTimeStyles.None,
out DateTime date))
{
if (!DateTime.TryParse(
dateTrim,
System.Globalization.CultureInfo.InvariantCulture,
System.Globalization.DateTimeStyles.None,
out date))
{
return DateTime.MinValue;
}
}
// Parse TIME: H:m:s.fff (variable precision).
string[] timeFormats =
{
"H:m:s.fff", "H:m:s.ff", "H:m:s.f", "H:m:s",
"HH:mm:ss.fff", "HH:mm:ss.ff", "HH:mm:ss.f", "HH:mm:ss",
};
string timeTrim = xmlTime!.Trim();
if (!DateTime.TryParseExact(
timeTrim,
timeFormats,
System.Globalization.CultureInfo.InvariantCulture,
System.Globalization.DateTimeStyles.None,
out DateTime time))
{
if (!DateTime.TryParse(
timeTrim,
System.Globalization.CultureInfo.InvariantCulture,
System.Globalization.DateTimeStyles.None,
out time))
{
return DateTime.MinValue;
}
}
// DATE + TIME are UTC as delivered; GMTOFFSET / DSTADJUST are not
// applied (see remarks, mxaccessgw#226).
return new DateTime(
date.Year, date.Month, date.Day,
time.Hour, time.Minute, time.Second, time.Millisecond,
DateTimeKind.Utc);
}
}