feat(uns): equipment CRUD with #122 driver-cluster guard

2026-06-08 12:47:19 -04:00
parent 8b1d3de806
commit 2836a0704b
4 changed files with 523 additions and 0 deletions
@@ -100,4 +100,40 @@ public interface IUnsTreeService
    /// <param name="ct">A token to cancel the operation.</param>
    /// <returns>Success, a concurrency failure, or a delete-failed failure.</returns>
    Task<UnsMutationResult> DeleteLineAsync(string unsLineId, byte[] rowVersion, CancellationToken ct = default);
+
+    /// <summary>
+    /// Creates a new equipment under a UNS line. The <c>EquipmentId</c> is system-generated
+    /// (decision #125: <c>EQ-</c> + the first 12 hex chars of a fresh <c>EquipmentUuid</c>).
+    /// Fails if the line is unset, if the MachineCode is already used fleet-wide, or if the
+    /// decision-#122 driver-cluster guard trips. Whitespace-only DriverInstanceId/ZTag/SAPID
+    /// collapse to <c>null</c>.
+    /// </summary>
+    /// <param name="input">The operator-editable equipment fields.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, a missing-line failure, a duplicate-MachineCode failure, or a #122 guard failure.</returns>
+    Task<UnsMutationResult> CreateEquipmentAsync(EquipmentInput input, CancellationToken ct = default);
+
+    /// <summary>
+    /// Updates an equipment's mutable fields (driver binding, line, name, MachineCode, external
+    /// ids, and the OPC 40010 identification fields). The decision-#122 driver-cluster guard blocks
+    /// binding to a driver in a different cluster than the equipment's line. Uses last-write-wins
+    /// optimistic concurrency on <see cref="Configuration.Entities.Equipment.RowVersion"/>.
+    /// </summary>
+    /// <param name="equipmentId">The equipment to update.</param>
+    /// <param name="input">The new operator-editable equipment fields.</param>
+    /// <param name="rowVersion">The concurrency token the caller last read.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, a missing-row failure, a #122 guard failure, or a concurrency failure.</returns>
+    Task<UnsMutationResult> UpdateEquipmentAsync(string equipmentId, EquipmentInput input, byte[] rowVersion, CancellationToken ct = default);
+
+    /// <summary>
+    /// Deletes an equipment. A missing row is treated as success (already gone). Uses last-write-wins
+    /// optimistic concurrency; a delete that fails because tags or virtual tags still reference the
+    /// equipment surfaces a guidance message.
+    /// </summary>
+    /// <param name="equipmentId">The equipment to delete.</param>
+    /// <param name="rowVersion">The concurrency token the caller last read.</param>
+    /// <param name="ct">A token to cancel the operation.</param>
+    /// <returns>Success, a concurrency failure, or a delete-failed failure.</returns>
+    Task<UnsMutationResult> DeleteEquipmentAsync(string equipmentId, byte[] rowVersion, CancellationToken ct = default);
 }