lmxopcua/docs/plans/2026-06-16-stillpending-phase-6-adminui.md

Phase 6 — AdminUI Typed Editors, Pickers & UX — Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development to implement this plan task-by-task. Execution is post-compaction — start by reading this plan + docs/plans/2026-06-16-stillpending-phase-6-adminui-design.md. Branch feat/stillpending-phase-6-adminui (off master 156aa900) already exists with the design committed (dbff29dd).

Goal: Complete the /uns Tag authoring UX — typed editors for every driver, historized fields as first-class controls, native-alarm AVEVA opt-out, address pickers reachable from the Tag modal, UNS-tree deletes for the top node kinds, and create-new-script from the inline vtag panel.

Architecture: Blazor Server AdminUI under src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/. Pure-C# cores (*TagConfigModel FromJson/ToJson/Validate, UnsTreeService methods, alarm sub-model) are unit-tested in tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/; Razor shells are proven only by live /run (NO bUnit). NO EF migration, NO Commons contract change.

Global rules (every task): TDD red→green for the pure cores. Stage by path — never git add .; never stage sql_login.txt, src/Server/.../Host/pki/, pending.md, current.md, docker-dev/docker-compose.yml, stillpending.md. No --no-verify, no force-push. NO EF migration. Preserve the *TagConfigModel preserve-unknown-keys contract. If git commit hits .git/index.lock (concurrent sibling), wait 2s + retry up to 5×.

Dependency graph: Task1→Task2→Task5 (same TagEditors files, serial). Task3→Task4 (alarm form, serial). Task6, Task7 independent. Concurrent start: Tasks 1, 3, 6, 7 (disjoint files). Then 2 (after 1), 4 (after 3), 5 (after 2).

---

Task 0: Feature branch (done)

Branch feat/stillpending-phase-6-adminui off 156aa900; design committed dbff29dd. No action.

---

Task 1 (A): Typed editors for OpcUaClient + Historian.Wonderware

Classification: standard · Est: ~5 min · Parallelizable with: Task 3, 6, 7

Files:

• Create: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/OpcUaClientTagConfigModel.cs
• Create: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/HistorianWonderwareTagConfigModel.cs
• Create: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Uns/TagEditors/OpcUaClientTagConfigEditor.razor
• Create: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Uns/TagEditors/HistorianWonderwareTagConfigEditor.razor
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/TagConfigEditorMap.cs (register "OpcUaClient" + "Historian.Wonderware")
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/TagConfigValidator.cs (register both)
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Uns/OpcUaClientTagConfigModelTests.cs, .../HistorianWonderwareTagConfigModelTests.cs

Approach: Read ModbusTagConfigModel.cs + its editor + ModbusTagConfigModelTests.cs as the exact template. The OpcUaClient tag-config carries the OPC UA FullName/NodeId + (poll) settings; the Historian tag-config carries the historian tagname/source. Inspect each driver's TagConfig shape (the OpcUaClient driver's equipment-tag ref + the Historian client options) for the real fields; keep preserve-unknown-keys. Register exact DriverType strings ("OpcUaClient", "Historian.Wonderware" — confirm against GalaxyDriverFactoryExtensions.DriverTypeName-style constants / DriverFactoryBootstrap).

Steps: (1) Write failing model tests (FromJson/ToJson round-trip + Validate + unknown-key preservation). (2) Run → fail. (3) Implement the 2 models + editors + register. (4) Tests green. (5) dotnet build the AdminUI project clean. (6) Commit feat(adminui): typed TagConfig editors for OpcUaClient + Historian.

---

Task 2 (B): isHistorized / historianTagname first-class fields

Classification: standard · Est: ~5 min · Parallelizable with: Task 6, 7 · blockedBy: Task 1

Files:

• Modify: every src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Uns/TagEditors/*TagConfigModel.cs (add IsHistorized/HistorianTagname round-trip on FromJson/ToJson, keys isHistorized/historianTagname)
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Uns/TagModal.razor (a shared "Historize this tag" checkbox + optional "Historian tagname" textbox, driver-agnostic, above/below the typed-editor slot)
• Test: tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/Uns/HistorizedFieldRoundTripTests.cs

Approach: The server already reads isHistorized/historianTagname from the raw TagConfig JSON (docs/Historian.md); this surfaces them as controls without changing the wire format. Decide ONE seam: either each typed model carries the two fields, OR the TagModal merges them into the JSON around the typed editor (simpler + uniform + covers the raw-JSON fallback drivers). Prefer the TagModal-merge seam so it works for ALL drivers incl. raw-JSON ones, and unit-test the merge helper. Confirm round-trip byte-parity (toggle → save → reopen shows the toggle; a changed=1 deploy per the H1 work).

Steps: TDD the merge/round-trip helper → implement → green → build → commit feat(adminui): isHistorized + historianTagname as first-class Tag fields.

---

Task 3 (C): Native-alarm HistorizeToAveva opt-out

Classification: standard · Est: ~5 min · Parallelizable with: Task 1, 6, 7

Files:

• Modify: the native-alarm authoring surface — find it (grep TagModal/equipment Alarms tab for the native-alarm alarm object; native alarms ride TagConfig.alarm, NOT the ScriptedAlarm entity). Likely a new small alarm sub-model + a control in TagModal.razor (or the typed editors' alarm section).
• Verify: src/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer/Phase7Composer.cs EquipmentTagAlarmInfo — add/confirm HistorizeToAveva (bool?) parse from TagConfig.alarm, and that HistorianAdapterActor gates native-alarm durable writes on is not false (the scripted path already does — mirror it).
• Test: tests/.../AdminUI.Tests/Uns/NativeAlarmHistorizeModelTests.cs (+ a Phase7Composer parse test if the carrier changes)

Approach: Add historizeToAveva (bool?, absent ⇒ historize) to the native-alarm TagConfig.alarm model + a "Historize to AVEVA" checkbox in the native-alarm form. Confirm the server honors it for native alarms (the scripted-alarm gate shipped in the script-log/alarm round-3 — find the is not false check in HistorianAdapterActor and ensure native transitions pass through the same gate). NO migration (rides TagConfig). TDD the model field; live /run the toggle.

Steps: TDD → implement model + UI + server-honor confirmation → green → build → commit feat(adminui): native-alarm HistorizeToAveva opt-out.

---

Task 4 (D): Galaxy picker pre-fills alarm fields from IsAlarm

Classification: small · Est: ~4 min · Parallelizable with: Task 5, 6, 7 · blockedBy: Task 3

Files:

• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Shared/Drivers/Pickers/GalaxyAddressPickerBody.razor + its selection callback into TagModal.razor:115
• Test: none new (pure Razor wiring) — covered by live /run

Approach: DriverAttributeInfo.IsAlarm already exists (Core.Abstractions/DriverAttributeInfo.cs:55). When the Galaxy picker returns a selection whose attribute IsAlarm == true, pre-fill the native-alarm sub-form (from Task 3) with sensible defaults (alarm type/severity) so the operator authors the alarm in one pass. Wiring only. Commit feat(adminui): Galaxy picker pre-fills native-alarm fields from IsAlarm.

---

Task 5 (E): "Build address" button in the protocol-driver typed editors

Classification: small · Est: ~5 min · Parallelizable with: Task 6, 7 · blockedBy: Task 2

Files:

• Modify: the 6 typed editors Components/Shared/Uns/TagEditors/{Modbus,S7,AbCip,AbLegacy,TwinCAT,Focas}TagConfigEditor.razor — add a "Build address" button that opens the matching existing Components/Shared/Drivers/Pickers/*AddressPickerBody.razor inside the shared DriverTagPicker shell, writing the built address back to the editor's address field.
• Test: none new (the *AddressBuilder cores are already unit-tested under AdminUI.Tests/Pickers/) — live /run

Approach: Reuse the EXACT pattern by which Galaxy is wired into TagModal.razor:115 (<DriverTagPicker @bind-Visible=…><XAddressPickerBody …/></DriverTagPicker>), but per typed editor. No new picker logic. Commit feat(adminui): Build-address pickers in the protocol-driver Tag editors.

---

Task 6 (F): UNS-tree Delete for Cluster / Enterprise

Classification: standard · Est: ~6 min · Parallelizable with: Task 1, 3, 7

Files:

• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/... IUnsTreeService + UnsTreeService (add DeleteClusterAsync(clusterId, rowVersion); add RowVersion to ClusterRow + query it in LoadStructureAsync)
• Modify: Components/Shared/Uns/UnsTree.razor (RenderActions → Delete action for Cluster), Components/Pages/Uns/GlobalUns.razor (ConfirmDeleteAsync:306 Cluster/Enterprise branch)
• Test: tests/.../AdminUI.Tests/Uns/UnsTreeServiceDeleteClusterTests.cs (in-memory EF — delete empty cluster ok; refuse-or-cascade with children; RowVersion mismatch → concurrency error; Enterprise = delete all clusters under the label)

Approach: Mirror the existing DeleteAreaAsync/DeleteLineAsync pattern. Cluster cascade is the danger (owns driver-instances + areas→…→tags) — decide refuse-if-children vs ordered cascade and TEST it; require RowVersion concurrency. Enterprise is a tree label (not a DB entity) ⇒ delete all clusters carrying that Enterprise value. Service unit-tested; tree action live /run. Commit feat(adminui): UNS-tree delete for Cluster + Enterprise.

---

Task 7 (G): Create-new-script from the inline virtual-tag panel

Classification: standard · Est: ~5 min · Parallelizable with: Task 1, 3, 6

Files:

• Modify: IUnsTreeService + UnsTreeService (add CreateScriptAsync(...) → new Script row, generated id, blank source, returns the new id)
• Modify: src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/.../VirtualTagModal.razor (:66 — a "New script" branch when ScriptId is empty → CreateScriptAsync → bind → expand the inline Monaco editor)
• Test: tests/.../AdminUI.Tests/Uns/UnsTreeServiceCreateScriptTests.cs (in-memory EF — creates a Script row with a unique id + blank source)

Approach: SetVirtualTag completions/hover already work (no change). Add only the create-new-script flow. Service unit-tested; UX live /run. Commit feat(adminui): create-new-script from the inline virtual-tag panel.

---

Task 8: Docs + bookkeeping

Classification: small · Est: ~4 min · blockedBy: Task 1–7

Update docs/Uns.md (typed editors for OpcUaClient/Historian, historized first-class fields, Build-address pickers, Cluster/Enterprise delete, create-new-script) + docs/Historian.md (isHistorized/historianTagname now first-class) + a native-alarm HistorizeToAveva note in docs/ScriptedAlarms.md/docs/AlarmTracking.md. Note Item 7 (Hosts page) deferred (F7-blocked). Commit docs(phase6): AdminUI editors, pickers, deletes, new-script.

---

Task 9: Full build + test + final integration review

Classification: high-risk · Est: ~6 min · blockedBy: Task 1–8

dotnet build ZB.MOM.WW.OtOpcUa.slnx → 0 errors. dotnet test tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests → green (+ any touched OpcUaServer test for Task 3's composer parse). Final integration review: (a) preserve-unknown-keys holds across the historized-field + alarm additions; (b) Cluster delete cascade/concurrency is safe; (c) no EF migration / no Commons contract change leaked; (d) the native-alarm historize gate matches the scripted path. Fix findings, commit.

---

Task 10: Live /run acceptance (agent-driven)

Classification: high-risk · Est: ~10 min · blockedBy: Task 9

Bring up the local rig: docker compose -f docker-dev/docker-compose.yml up -d central-1 (+ the AdminUI service; login disabled). Drive http://localhost:9200 via the Chrome browser tools: author an OpcUaClient + a Historian tag via the new typed editors; toggle Historize + set a historian tagname → deploy → confirm changed=1 + round-trip on reopen; toggle a native-alarm AVEVA opt-out; open a protocol-driver "Build address" picker and use a built address; create + delete a disposable Cluster; create-new-script from the vtag panel. Phase-5 lesson: the Bash sandbox blocks some network — if a check can't reach a service, retry with dangerouslyDisableSandbox: true. Record results; honestly defer anything the local rig can't exercise.

---

Done =

Build clean + AdminUI.Tests green + final integration review SHIP + live /run acceptance pass. Then finishing-a-development-branch → merge to master + push (the user's standing directive). Update pending.md banner + the project_stillpending_backlog memory.