feat(alarms): thread an additive AckTime through the native-alarm mirror
MES alarm-status API §6.4 (docs/plans/2026-06-30-mes-alarm-status-api.md,
Phase 1 task 1). MES needs a real AckDT for a triggered alarm, and the mirror
carried acked-vs-unacked but never WHEN. AckTime now rides the whole path:
DCL transition -> AlarmStateChanged -> gRPC AlarmStateUpdate -> site SQLite.
Stamping rule, identical on both protocols: non-null ONLY while the condition
is active AND acknowledged. That single predicate yields all three required
behaviours -- null while unacked, cleared on re-raise (a re-raise arrives
unacknowledged), and no phantom ack on a return-to-normal. The last one is
load-bearing for MxGateway, which maps INACTIVE to Acknowledged = true; without
the active check every clear would claim an ack the system never observed.
Provenance is honest, never fabricated:
- OPC UA A&C supplies a TRUE ack instant, so we now select it:
AcknowledgeableConditionType/AckedState/TransitionTime at SelectClause
index 18, APPENDED so the positional reads at 0-17 keep their meaning.
Servers that omit the field fall back to the event's own Time.
- MxAccess Gateway supplies none, so the ack transition's own timestamp is
used -- accurate to when the system SAW the ack. An ACTIVE_ACKED
re-subscribe snapshot restores one from LastTransitionTimestamp rather
than dropping it.
The decision lives in pure mappers (Opc/Mx AlarmMapper.DeriveAckTime), so it is
unit-tested with no live server or gateway.
Additive-only throughout: init-only property on AlarmStateChanged, trailing
optional positional on NativeAlarmTransition (all 14-arg call sites untouched),
proto field 24 (never reusing a number) regenerated via docker/regen-proto.sh
sitestream with the csproj diff verified empty.
Persistence rides native_alarm_state's existing metadata_json blob rather than
a new column -- deliberately. That table is RegisterReplicated in
SiteLocalDbSetup and LocalDb builds its CDC triggers from the column list at
registration time, so an additive JSON property changes no schema, no triggers
and no replication contract; metadata_json is exactly the extension point UA4
introduced for this. Rows written before the field deserialize it as null.
Tests: 4 OPC UA + 6 MxGateway mapper cases, 3 NativeAlarmActor (emit,
failover rehydrate, pre-AckTime row), 1 proto round-trip incl. the null case,
4 Commons additive/back-compat. The OPC UA SelectClause count lock-in moves
18 -> 19 with an index-18 assertion -- intended, the clause is appended, which
is precisely what that guard exists to make visible.
This commit is contained in:
@@ -699,6 +699,16 @@ public class RealOpcUaClient : IOpcUaClient
|
||||
filter.SelectClauses.Add(SelectField(ObjectTypeIds.LimitAlarmType, "LowLimit")); // 16
|
||||
filter.SelectClauses.Add(SelectField(ObjectTypeIds.LimitAlarmType, "LowLowLimit")); // 17
|
||||
|
||||
// 18: AcknowledgeableConditionType/AckedState/TransitionTime — the UTC instant the
|
||||
// acked-state last flipped. When the condition is currently ACKED that instant IS
|
||||
// the moment of acknowledgement, so it is the true source ack time mapped to
|
||||
// NativeAlarmTransition.AckTime (MES alarm-status API §6.4). Optional — absent on
|
||||
// base ConditionType events and on servers that do not expose it, in which case
|
||||
// OpcUaAlarmMapper.DeriveAckTime falls back to the event's own Time field. Same
|
||||
// ConditionRefresh caveat as index 13: a replayed snapshot may re-stamp it.
|
||||
filter.SelectClauses.Add(
|
||||
SelectField(ObjectTypeIds.AcknowledgeableConditionType, "AckedState", "TransitionTime")); // 18
|
||||
|
||||
// UNAVAILABLE via standard OPC UA A&C event fields (documented here so future
|
||||
// maintainers know these were considered, not overlooked):
|
||||
// Category — not a standard event field; server-specific extensions only.
|
||||
@@ -848,6 +858,15 @@ public class RealOpcUaClient : IOpcUaClient
|
||||
fields.Count > 16 ? fields[16].Value : null,
|
||||
fields.Count > 17 ? fields[17].Value : null);
|
||||
|
||||
// Index 18: AckedState/TransitionTime → the true source ack instant when the condition
|
||||
// is currently acked. Absent on non-acknowledgeable events / servers that omit it →
|
||||
// guard + null fallback, which DeriveAckTime resolves to the event time below.
|
||||
DateTimeOffset? sourceAckTime = null;
|
||||
if (fields.Count > 18 && fields[18].Value is DateTime ackTransitionTime)
|
||||
// OPC UA mandates UTC for DateTime fields; TimeSpan.Zero treats an Unspecified
|
||||
// Kind as UTC (consistent with the Time and ActiveState/TransitionTime mappings).
|
||||
sourceAckTime = new DateTimeOffset(ackTransitionTime, TimeSpan.Zero);
|
||||
|
||||
var inRefresh = _alarmInRefresh.GetValueOrDefault(handle);
|
||||
var lastState = _alarmLastState.GetValueOrDefault(handle);
|
||||
var (prevActive, prevAcked) = lastState != null && lastState.TryGetValue(sourceRef, out var prev) ? prev : (false, true);
|
||||
@@ -876,7 +895,10 @@ public class RealOpcUaClient : IOpcUaClient
|
||||
TransitionTime: time,
|
||||
// UNAVAILABLE: CurrentValue not a standard A&C event field — see BuildAlarmEventFilter.
|
||||
CurrentValue: "",
|
||||
LimitValue: limitValue));
|
||||
LimitValue: limitValue,
|
||||
// MES alarm-status API §6.4: true source ack instant (index 18) when supplied,
|
||||
// else the observed event time; null unless the condition is active AND acked.
|
||||
AckTime: OpcUaAlarmMapper.DeriveAckTime(active, acked, sourceAckTime, time)));
|
||||
}
|
||||
|
||||
private static NativeAlarmTransition SnapshotComplete() => new(
|
||||
|
||||
Reference in New Issue
Block a user