Phase 6.4 Stream D server-side — IdentificationFolderBuilder materializes OPC 40010 Machinery Identification sub-folder

Closes the server-side / non-UI piece of Phase 6.4 Stream D. The Razor `IdentificationFields.razor` component for Admin-UI editing ships separately when the Admin UI pass lands (still tracked under #157 UI follow-up). Core.OpcUa additions: - IdentificationFolderBuilder — pure-function builder that materializes the OPC 40010 Machinery companion-spec Identification sub-folder per decision #139. Reads the nine nullable columns off an Equipment row: Manufacturer, Model, SerialNumber, HardwareRevision, SoftwareRevision, YearOfConstruction (short → OPC UA Int32), AssetLocation, ManufacturerUri, DeviceManualUri. Emits one AddProperty call per non-null field; skips the sub-folder entirely when all nine are null so browse trees don't carry pointless empty folders. - HasAnyFields(equipment) — cheap short-circuit so callers can decide whether to invoke Folder() at all. - FolderName constant ("Identification") + FieldNames list exposed so downstream tools / tests can cross-reference without duplicating the decision-#139 field set. ACL binding: the sub-folder + variables live under the Equipment node so Phase 6.2's PermissionTrie treats them as part of the Equipment ScopeId — no new scope level. A user with Equipment-level grant reads the Identification fields; a user without gets BadUserAccessDenied on both the Equipment node + its Identification variables. Documented in the class remarks; cross-reference update to acl-design.md is a follow-up. Tests (9 new IdentificationFolderBuilderTests): - HasAnyFields all-null false / any-non-null true. - Build all-null returns null + doesn't emit Folder. - Build fully-populated emits all 9 fields in decision #139 order. - Only non-null fields are emitted (3-of-9 case). - YearOfConstruction short widens to DriverDataType.Int32 with int value. - String values round-trip through AddProperty. - FieldNames constant matches decision #139 exactly. - FolderName is "Identification". Full solution dotnet test: 1202 passing (was 1193, +9). Pre-existing Client.CLI Subscribe flake unchanged. Production integration: the component that consumes this is the address-space-build flow that walks the live Equipment table + calls IdentificationFolderBuilder.Build(equipmentFolder, equipment) under each Equipment node. That integration is the remaining Stream D follow-up alongside the Razor UI component. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-19 11:57:39 -04:00
parent 0c903ff4e0
commit c1cab33e38
2 changed files with 249 additions and 0 deletions
--- a/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/IdentificationFolderBuilder.cs
+++ b/src/ZB.MOM.WW.OtOpcUa.Core/OpcUa/IdentificationFolderBuilder.cs
@@ -0,0 +1,91 @@
+using ZB.MOM.WW.OtOpcUa.Configuration.Entities;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+
+namespace ZB.MOM.WW.OtOpcUa.Core.OpcUa;
+
+/// <summary>
+///     Phase 6.4 Stream D: materializes the OPC 40010 Machinery companion-spec Identification
+///     sub-folder under an Equipment node. Reads the nine decision-#139 columns off the
+///     <see cref="Equipment"/> row and emits one property per non-null field.
+/// </summary>
+/// <remarks>
+///     <para>Pure-function shape — testable without a real OPC UA node manager. The caller
+///     passes the builder scoped to the Equipment node; this class handles the Identification
+///     sub-folder creation + per-field <see cref="IAddressSpaceBuilder.AddProperty"/> calls.</para>
+///
+///     <para>ACL binding: the sub-folder + its properties inherit the Equipment scope's
+///     grants (no new scope level). Phase 6.2's trie treats them as part of the Equipment
+///     ScopeId — a user with Equipment-level grant reads Identification; a user without the
+///     grant gets BadUserAccessDenied on both the Equipment node + its Identification variables.
+///     See <c>docs/v2/acl-design.md</c> §Identification cross-reference.</para>
+///
+///     <para>The nine fields per decision #139 are exposed exactly when they carry a non-null
+///     value. A row with all nine null produces no Identification sub-folder at all — the
+///     caller can use <see cref="HasAnyFields(Equipment)"/> to skip the Folder call entirely
+///     and avoid a pointless empty folder appearing in browse trees.</para>
+/// </remarks>
+public static class IdentificationFolderBuilder
+{
+    /// <summary>Browse + display name of the sub-folder — fixed per OPC 40010 convention.</summary>
+    public const string FolderName = "Identification";
+
+    /// <summary>
+    ///     Canonical decision #139 field set exposed in the Identification sub-folder. Order
+    ///     matches the decision-log entry so any browse-order reader can cross-reference
+    ///     without re-sorting.
+    /// </summary>
+    public static IReadOnlyList<string> FieldNames { get; } = new[]
+    {
+        "Manufacturer", "Model", "SerialNumber",
+        "HardwareRevision", "SoftwareRevision",
+        "YearOfConstruction", "AssetLocation",
+        "ManufacturerUri", "DeviceManualUri",
+    };
+
+    /// <summary>True when the equipment row has at least one non-null Identification field.</summary>
+    public static bool HasAnyFields(Equipment equipment)
+    {
+        ArgumentNullException.ThrowIfNull(equipment);
+        return equipment.Manufacturer is not null
+            || equipment.Model is not null
+            || equipment.SerialNumber is not null
+            || equipment.HardwareRevision is not null
+            || equipment.SoftwareRevision is not null
+            || equipment.YearOfConstruction is not null
+            || equipment.AssetLocation is not null
+            || equipment.ManufacturerUri is not null
+            || equipment.DeviceManualUri is not null;
+    }
+
+    /// <summary>
+    ///     Build the Identification sub-folder under <paramref name="equipmentBuilder"/>. No-op
+    ///     when every field is null. Returns the sub-folder builder (or null when no-op) so
+    ///     callers can attach additional nodes underneath if needed.
+    /// </summary>
+    public static IAddressSpaceBuilder? Build(IAddressSpaceBuilder equipmentBuilder, Equipment equipment)
+    {
+        ArgumentNullException.ThrowIfNull(equipmentBuilder);
+        ArgumentNullException.ThrowIfNull(equipment);
+
+        if (!HasAnyFields(equipment)) return null;
+
+        var folder = equipmentBuilder.Folder(FolderName, FolderName);
+        AddIfPresent(folder, "Manufacturer",       DriverDataType.String,   equipment.Manufacturer);
+        AddIfPresent(folder, "Model",              DriverDataType.String,   equipment.Model);
+        AddIfPresent(folder, "SerialNumber",       DriverDataType.String,   equipment.SerialNumber);
+        AddIfPresent(folder, "HardwareRevision",   DriverDataType.String,   equipment.HardwareRevision);
+        AddIfPresent(folder, "SoftwareRevision",   DriverDataType.String,   equipment.SoftwareRevision);
+        AddIfPresent(folder, "YearOfConstruction", DriverDataType.Int32,
+            equipment.YearOfConstruction is null ? null : (object)(int)equipment.YearOfConstruction.Value);
+        AddIfPresent(folder, "AssetLocation",      DriverDataType.String,   equipment.AssetLocation);
+        AddIfPresent(folder, "ManufacturerUri",    DriverDataType.String,   equipment.ManufacturerUri);
+        AddIfPresent(folder, "DeviceManualUri",    DriverDataType.String,   equipment.DeviceManualUri);
+        return folder;
+    }
+
+    private static void AddIfPresent(IAddressSpaceBuilder folder, string name, DriverDataType dataType, object? value)
+    {
+        if (value is null) return;
+        folder.AddProperty(name, dataType, value);
+    }
+}