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

Still-Pending Phase 6 — AdminUI typed editors, pickers & UX — design

Status: approved 2026-06-16 (scope = "Everything achievable", AskUserQuestion). Parent roadmap: docs/plans/2026-06-15-stillpending-backlog-design.md (Phase 6). Branch feat/stillpending-phase-6-adminui off master 156aa900. Phases 0–5 already shipped. Execution is deferred to AFTER a /compact — this doc + the implementation plan are the durable handoff.

Goal

Close the AdminUI authoring/UX gaps in stillpending.md §4 so the /uns Tag authoring experience is complete: typed editors for every driver, historized fields as first-class controls, native-alarm AVEVA opt-out, the existing address pickers reachable from the Tag modal, UNS-tree deletes for the top node kinds, and create-new-script from the inline virtual-tag panel. NO EF migration; Razor proven only by live /run (no bUnit) — the pure-C# *TagConfigModel / service / builder cores ARE unit-tested in tests/Server/ZB.MOM.WW.OtOpcUa.AdminUI.Tests/.

Grounding that reshaped the scope (the roadmap was materially stale)

1. DriverAttributeInfo.IsAlarm already exists (Core.Abstractions/DriverAttributeInfo.cs:55, plus IsArray/ArrayDim). Item 4 needs no Commons contract change — only the picker→modal pre-fill wiring.
2. All 9 driver address-picker bodies + builders already exist under Components/Shared/Drivers/Pickers/ ({Modbus,S7,AbCip,AbLegacy,TwinCAT,FOCAS,Galaxy,OpcUaClient, HistorianWonderware}AddressPickerBody.razor + the *AddressBuilder.cs with unit tests under tests/.../AdminUI.Tests/Pickers/). They are wired into the per-cluster driver pages (ModbusDriverPage.razor …). Only the Galaxy picker is also wired into the /uns TagModal.razor (:115). So the roadmap's "only OpcUaClient + Galaxy pickers shipped" is stale; Item 5's residue is just wiring a "Build address" affordance into the typed editors in the Tag modal.
3. ctx.SetVirtualTag(...) completions/hover are already wired — SetVirtualTag is already in ScriptAnalysisService.TryGetTagPathLiteral. Item 8's residue is only create-new-script from the inline panel.
4. HistorizeToAveva is a first-class field on scripted alarms (ScriptedAlarm entity + Phase7Composer.ScriptedAlarmInfo; the ScriptedAlarmModal toggle already ships). Item 3's residue is the native-alarm side: the TagConfig.alarm object's AVEVA opt-out + its UI.
5. No bUnit anywhere — the AdminUI test project (AdminUI.Tests) is pure C# (model FromJson/ToJson/ Validate tests, UnsTreeService* against in-memory EF, ScriptAnalysis/*, Pickers/*AddressBuilder).

In scope — the genuinely-remaining work (Item 7 deferred)

A. Typed editors for OpcUaClient + Historian.Wonderware (Item 1) — standard

• TagConfigEditorMap (Uns/TagEditors/TagConfigEditorMap.cs) maps only ModbusTcp/S7/AbCip/AbLegacy/TwinCat/ Focas → a typed editor; OpcUaClient/Galaxy/Historian.Wonderware fall back to raw JSON.
• Add OpcUaClientTagConfigModel + HistorianWonderwareTagConfigModel (pure FromJson/ToJson/Validate, preserve-unknown-keys, camelCase) + their razor editor shells under Components/Shared/Uns/TagEditors/, register both in TagConfigEditorMap + TagConfigValidator. Mirror the Modbus template.
• Unit-test the two models (mirror ModbusTagConfigModelTests); editors proven by live /run.

B. isHistorized / historianTagname as first-class fields (Item 2) — standard

• Today they ride the raw TagConfig JSON (the server already reads them — docs/Historian.md).
• Surface a shared "Historize this tag" checkbox + optional "Historian tagname" textbox in the Tag modal, driver-agnostic (applies to any equipment tag). Thread them through the typed-editor models' FromJson/ ToJson (and the raw-JSON fallback) so a toggle round-trips byte-parity and is preserved across edits.
• Unit-test the field round-trip on the models.

C. Native-alarm HistorizeToAveva opt-out (Item 3) — standard

• The native-alarm carrier is TagConfig.alarm (Phase7Composer.EquipmentTagAlarmInfo). Add a historizeToAveva (bool?, default-historize when absent — mirror the scripted-alarm wire contract) to the native-alarm authoring surface + the alarm sub-model, and confirm the server honors it for native alarms in HistorianAdapterActor (the scripted path already gates on is not false). NO migration (rides TagConfig). Unit-test the model field; live /run the toggle.

D. Galaxy picker pre-fills alarm fields from IsAlarm (Item 4) — small

• DriverAttributeInfo.IsAlarm already exists. When the Galaxy address picker (wired in TagModal.razor:115) returns a selection whose attribute IsAlarm == true, pre-fill the native-alarm sub-form (from C) with sensible defaults so the operator can author the alarm in one pass. Wiring only; live /run.

E. Address pickers reachable from the typed editors (Item 5) — small

• The picker bodies + builders exist and are wired on the driver pages. Add a "Build address" button to each protocol-driver typed editor (Modbus/S7/AbCip/AbLegacy/TwinCAT/Focas) in the Tag modal that opens the matching *AddressPickerBody inside the shared DriverTagPicker shell (exactly as Galaxy is wired at TagModal.razor:115), writing the built address back into the editor's address field. Reuses existing bodies — no new picker logic. Live /run.

F. UNS-tree Delete for Cluster / Enterprise (Item 6) — standard

• GlobalUns.ConfirmDeleteAsync (:306) guards Enterprise/Cluster as "not yet available"; UnsTree's RenderActions hides Delete for those kinds. Add IUnsTreeService.DeleteClusterAsync(clusterId, rowVersion) (+ ClusterRow.RowVersion, queried in LoadStructureAsync), the UnsTree Delete action for Cluster, and the GlobalUns branch. Enterprise = delete all clusters under that label (Enterprise is a tree label, not a DB entity). Cluster cascade is the danger (it owns driver-instances + areas→lines→equipment→tags) — match the area/line pattern (refuse-if-children OR ordered cascade) and require RowVersion concurrency. Service- layer unit-tested against in-memory EF (mirror UnsTreeService* tests); the tree action is live /run.

G. Create-new-script from the inline virtual-tag panel (Item 8) — small

• VirtualTagModal.razor (:66) shows the inline Monaco editor only for an existing bound script. Add a "New script" branch (when ScriptId is empty) → IUnsTreeService.CreateScriptAsync(...) (new Script row, generated id, blank source) → bind it → expand the inline editor. Service-layer unit-tested; UX live /run.

Out of scope / deferred

• Item 7 — Hosts page per-driver-instance rows: DEFERRED (Hosts.razor is per-Akka-member; its own comment says driver-instance child rows "land with F7", which is not yet implemented → blocked on runtime work, not an AdminUI gap). Recorded as a Phase-6b/F7 follow-up.
• Phase-4b driver structural work; Phases 7–8.

Architecture / risk notes

• Independence: A+B are coupled (same model/editor files — do as one pass). C+D are coupled (D pre-fills C's form). E, F, G are independent. F + G are the service-layer (in-memory-EF-testable) items; A,B,C are model-layer testable; D,E are pure Razor wiring (live-/run only).
• No EF migration, no Commons contract change (IsAlarm/IsArray already on DriverAttributeInfo; historized
  • native-alarm-historize ride TagConfig JSON; ScriptedAlarm.HistorizeToAveva column already exists).
• The *TagConfigModel preserve-unknown-keys contract (per docs/plans/2026-06-09-driver-typed-tag-editors- design.md) MUST hold so adding historized fields never drops a driver's existing keys.

Testing & verification

• TDD red→green (xUnit + Shouldly) for every pure core: the 2 new *TagConfigModels (A), the historized-field round-trip (B), the native-alarm-historize model field (C), DeleteClusterAsync (F), CreateScriptAsync (G) — all in AdminUI.Tests (model tests + UnsTreeService in-memory-EF tests). No bUnit.
• dotnet build clean + dotnet test green before merge.
• Live /run (agent-driven, login disabled on the local rig): drive http://localhost:9200 — author an OpcUaClient/Historian tag via the new typed editor; toggle Historize + set a historian tagname and confirm round-trip on re-open + deploy; toggle native-alarm AVEVA opt-out; open a protocol-driver "Build address" picker and use a built address; delete a (disposable) Cluster; create-new-script from the vtag panel. NOTE (Phase-5 lesson): dotnet test of the integration suite is network-sandboxed — run live checks against the docker-dev rig accordingly; bring up the rig with docker compose -f docker-dev/docker-compose.yml up -d central-1. Final integration review before merge.

Hard constraints (carried from the parent roadmap)

• NO Configuration entity / EF migration. No Commons contract change. 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. Never echo or commit secrets. No force-push, no --no-verify. Finish = merge to master + push.