feat(commons): EquipmentNodeIds — single source of truth for folder-scoped equipment NodeIds

2026-06-13 06:26:59 -04:00
parent 891f875f6a
commit 26816fd17e
2 changed files with 55 additions and 0 deletions
@@ -0,0 +1,31 @@
+namespace ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+/// <summary>
+///     Single source of truth for equipment-namespace OPC UA NodeId strings. The variable NodeId is
+///     FOLDER-SCOPED (<c>{parent}/{Name}</c>), NOT the driver-side FullName — a driver wire ref is not
+///     unique across identical machines, so FullName-as-NodeId would collide in the sink. Used by the
+///     materialiser (Phase7Applier), the VirtualTag publish map, and the driver live-value router so all
+///     three agree on the exact NodeId a variable was placed at.
+/// </summary>
+public static class EquipmentNodeIds
+{
+    /// <summary>The sub-folder NodeId under an equipment for a non-empty FolderPath: <c>{equipmentId}/{folderPath}</c>.</summary>
+    /// <param name="equipmentId">The owning equipment's NodeId.</param>
+    /// <param name="folderPath">The tag/vtag FolderPath (must be non-empty for this to be meaningful).</param>
+    /// <returns>The sub-folder NodeId string.</returns>
+    public static string SubFolder(string equipmentId, string folderPath) => $"{equipmentId}/{folderPath}";
+
+    /// <summary>
+    ///     The folder-scoped variable NodeId: <c>{parent}/{name}</c> where <c>parent = equipmentId</c> when
+    ///     <paramref name="folderPath"/> is null/empty, else <see cref="SubFolder"/>.
+    /// </summary>
+    /// <param name="equipmentId">The owning equipment's NodeId.</param>
+    /// <param name="folderPath">The tag/vtag FolderPath, or null/empty for "directly under the equipment".</param>
+    /// <param name="name">The tag/vtag Name (the leaf browse segment).</param>
+    /// <returns>The folder-scoped variable NodeId string.</returns>
+    public static string Variable(string equipmentId, string? folderPath, string name)
+    {
+        var parent = string.IsNullOrWhiteSpace(folderPath) ? equipmentId : SubFolder(equipmentId, folderPath);
+        return $"{parent}/{name}";
+    }
+}
@@ -0,0 +1,24 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Commons.OpcUa;
+
+namespace ZB.MOM.WW.OtOpcUa.Commons.Tests.OpcUa;
+
+public class EquipmentNodeIdsTests
+{
+    [Fact]
+    public void Variable_with_no_folder_is_equipment_slash_name()
+        => EquipmentNodeIds.Variable("eq-1", "", "speed").ShouldBe("eq-1/speed");
+
+    [Fact]
+    public void Variable_with_null_folder_is_equipment_slash_name()
+        => EquipmentNodeIds.Variable("eq-1", null, "speed").ShouldBe("eq-1/speed");
+
+    [Fact]
+    public void Variable_with_folder_is_equipment_slash_folder_slash_name()
+        => EquipmentNodeIds.Variable("eq-1", "registers", "speed").ShouldBe("eq-1/registers/speed");
+
+    [Fact]
+    public void SubFolder_is_equipment_slash_folder()
+        => EquipmentNodeIds.SubFolder("eq-1", "registers").ShouldBe("eq-1/registers");
+}