docs: native alarm ingestion across component docs + CLAUDE.md

2026-05-31 02:55:00 -04:00
parent 2b7c765a58
commit 003e54c1fb
9 changed files with 265 additions and 6 deletions
@@ -45,6 +45,13 @@ Central cluster only. Sites have no user interface.
 - Manage template hierarchy (inheritance) — visual tree of parent/child relationships.
 - Manage composition — add/remove feature module instances within templates. **Naming collision detection** provides immediate feedback if composed modules introduce duplicate attribute, alarm, or script names.
 - Define and edit attributes, alarms, and scripts on templates.
+- **Native Alarms tab** (`TemplateEdit`): a tab alongside Attributes / Alarms / Scripts / Compositions that lists the template's **native alarm source bindings** — the OPC UA Alarms & Conditions / MxAccess Gateway sources whose alarm state the instance mirrors. Each binding carries Name, Connection, Source Reference, optional Condition Filter, Description, and a Lock flag. Add / edit / delete go through a **modal**:
+  - **Name** — unique within the template (lock/inherit bookkeeping mirrors `TemplateAlarm`).
+  - **Connection** — a dropdown filtered to **alarm-capable connections only** (OPC UA and MxGateway protocols).
+  - **Source Reference** — the native key (OPC UA SourceNode / notifier nodeId, or MxAccess object/area).
+  - **Condition Filter** (optional) — blank mirrors *all* conditions under the source.
+  - **Description** (optional) and **Lock** (prevents instance-level override, like locked alarms/attributes).
+  - CRUD is **repository-direct** (Blazor Server runs in-process against `ICentralUiRepository`); no Akka round-trip is needed for design-time authoring.
 - Set lock flags on attributes, alarms, and scripts.
 - Visual indicator showing inherited vs. locally defined vs. overridden members.
 - **On-demand validation**: A "Validate" action allows Design users to run comprehensive pre-deployment validation (flattening, naming collisions, script compilation, trigger references) without triggering a deployment. Provides early feedback during authoring.
@@ -97,6 +104,11 @@ Central cluster only. Sites have no user interface.
  - **Override** — optional per-attribute OPC UA node id (or other protocol address). When set, replaces the template's `DataSourceReference` at flattening time; when blank, the template default is used. The greyed placeholder shows the template default for context.
  - **Browse…** — opens the OPC UA Tag Browser dialog, populated live from the site's OPC UA server via `BrowseOpcUaNodeCommand`. Visible only when the row's connection uses the OPC UA protocol; disabled until a connection is picked on that row. The dialog lazy-loads the address space, supports manual node-id entry as a fallback, and remains usable when the site or its OPC UA session is offline (the manual-paste field stays active even on error).
 - Set instance-level attribute overrides (non-locked attributes only).
+- **Native Alarm Source Overrides card** (`InstanceConfigure`): a card placed **after the Alarm Overrides card**, listing the template's native alarm sources for per-instance binding. Each row offers **inline override** of the three fields that typically vary per physical instance:
+  - **Connection** — a dropdown (same alarm-capable filtering as the template editor).
+  - **Source Reference** — the concrete native key for this instance.
+  - **Filter** — the per-instance condition filter.
+  - A **blank field inherits** the template default (the greyed placeholder shows the inherited value for context, mirroring the per-attribute Override field). **Save** and **Clear** act per row — Save persists the row's overrides, Clear reverts the row to the template-inherited binding. Locked template sources are not overridable.
 - Filter/search instances by site, area, template, or status.
 - **Disable** instances — stops data collection, script triggers, and alarm evaluation at the site while retaining the deployed configuration.
 - **Enable** instances — re-activates a disabled instance.
@@ -127,6 +139,18 @@ Central cluster only. Sites have no user interface.
 - Stream includes attribute values formatted as `[InstanceUniqueName].[AttributePath].[AttributeName]` and alarm states formatted as `[InstanceUniqueName].[AlarmName]`.
 - Subscribe-on-demand — stream starts when opened, stops when closed.

+#### Alarm Table (Computed + Native)
+
+The DebugView alarm table is the **only** runtime surface for native OPC UA Alarms & Conditions and MxAccess Gateway alarms (no dedicated operator/alarm-summary page). Native alarms are a **read-only mirror** of source-reported state — the source system owns the alarm lifecycle (ack / shelve / suppress), so the table never offers ack-back or any command action. Both enriched `AlarmStateChanged` events (live, via the gRPC stream) and the initial `DebugViewSnapshot` (via ClusterClient) carry the unified alarm shape, so native alarms appear on the first paint and update in place. The table is a custom Blazor + Bootstrap component (no third-party grid).
+
+- **Kind column** — a badge distinguishing **Computed** alarms from native ones (an **OPC UA** or **MxAccess** badge), driven by the event's `AlarmKind` discriminator.
+- **Sev column** — the unified **0–1000 severity** (`AlarmConditionState.Severity`) shown for every row. Computed rows surface their integer priority on the same scale.
+- **Source reference subtitle** — for native rows, the `SourceReference` (e.g. `Tank01.Level.HiHi`) renders as a **monospace subtitle under the alarm name**. Computed rows have no subtitle and render exactly as before this change.
+- **State cell composite badges** — the orthogonal condition sub-states roll up into badges shown beside the active/normal state: **Unacked**, **Shelved**, and **Suppressed** appear only when the corresponding `AlarmConditionState` flag is set. Computed alarms are auto-acked and never shelved/suppressed, so they show none of these.
+- **Row tooltip** — hovering a row surfaces the native metadata that does not warrant its own column: alarm type (`AlarmTypeName`), category, operator user and comment (source-supplied ack metadata, display-only), original raise time, and the current/limit value.
+- **Filter** — the existing alarm filter additionally matches the native `SourceReference` (in addition to the alarm name), so operators can find a mirrored condition by its source path.
+- **Computed alarms render unchanged** — no Kind badge styling change, no subtitle, no new state badges beyond what the unified model implies; the enrichment is purely additive for native rows.
+
 ### Parked Message Management (Deployment Role)
 - Query sites for parked messages (external system calls, cached DB writes). (Parked notifications are managed centrally on the Notification Outbox page, not here.)
 - View message details (target, payload, retry count, timestamps).