lmxopcua/docs/plans/2026-05-29-adminui-followups-design.md

Design — Complete AdminUI deferred follow-ups

Date: 2026-05-29 Status: Approved (design); implementation plan to follow Author: Joseph Doherty (with Claude Code)

Background

The AdminUI carried a family of "deferred / Phase C.2 follow-up" notes. A prior change stripped the stale rendered roadmap banners from the cluster list pages. Three remaining note groups were investigated to decide what real work they hide:

• Group 1 — driver-page inline notes ("list-editor coming in a follow-up phase" for tags/devices/endpoints; "typed-form-ifying Polly is a follow-up"). → Real pending UI work.
• Group 2 — RoleGrants ("UI-driven editing of the mapping is deferred — it implies a config-reload mechanism that doesn't exist yet"). → Real work; half the infra already exists.
• Group 3 — source comments (F15 Razor migration, F16 FleetStatusHub bridge, "Phase 4" identity section, TODO(3.3/3.4) route collision). → ~90% stale; the referenced work already shipped (the F16 bridge is wired; the legacy DriverEdit.razor no longer exists). Only the Polly typed form is real, and it is already counted in Group 1.

Key facts established during exploration

• Driver-embedded tag/device lists in DriverConfig JSON are the runtime source of truth. Driver factories deserialize them and poll exactly those rows; the canonical Tag table is orthogonal (OPC UA browse-tree only, never read by drivers). So inline editors are meaningful, not redundant — editing them changes what the driver polls on the next publish/reinitialize.
• Resilience already has a strongly-typed model: DriverResilienceOptions (BulkheadMaxConcurrent, BulkheadMaxQueue, RecycleIntervalSeconds, CapabilityPolicies: {DriverCapability → (TimeoutSeconds, RetryCount, BreakerFailureThreshold)}) with tier A/B/C defaults via GetTierDefaults(tier) and a DriverResilienceOptionsParser. The stored JSON is an override shape; null/absent keys fall back to tier defaults.
• LDAP role map: the LdapGroupRoleMapping entity + migration + ILdapGroupRoleMappingService (CRUD) already exist but are not wired into login. LdapAuthService still reads the static appsettings GroupToRole (Dictionary<string,string>). RoleGrants.razor is read-only.
• Testing: no bUnit. Established pattern = test FromOptions/ToOptions round-trips (xUnit + Shouldly in AdminUI.Tests) and services with in-memory EF (Configuration.Tests).

Decisions

• Scope: full build — all real follow-ups in Groups 1 & 2, plus Group 3 comment cleanup.
• List-editor UX: modal-per-row with a shared shell component.
• LDAP reload semantics: DB-backed, live on the user's next sign-in (per-login DB query; no restart, no new infra). appsettings GroupToRole becomes a bootstrap fallback layer.
• Roles are GLOBAL. No cluster-level permissions / no per-cluster enforcement (explicitly chosen for simplicity, reversing an earlier cluster-scoping answer). Every LdapGroupRoleMapping row is IsSystemWide=true, ClusterId=null.

Workstreams

WS1 — Driver collection editors (modal-per-row + shared shell)

• New generic CollectionEditor<TRow> component in Components/Shared/Drivers/: compact read-only table + [+ Add] / per-row Edit / Delete, and a Bootstrap modal editing a working copy of a row (commit on modal-Save, discard on Cancel). Parameters: List<TRow> Items (bound), header fragment, read-only-cells fragment, modal-body fragment, NewRow factory, optional Validate delegate.
• Each driver page swaps its read-only <pre> for a CollectionEditor supplying its own columns + modal fields. Edits mutate the in-memory List<T> already in the page's FormModel; the page's existing Save serializes it into DriverConfig — no new persistence path.
• Coverage: tags (Modbus, AbCip, AbLegacy, TwinCAT, S7, FOCAS); devices (AbCip, AbLegacy, TwinCAT, FOCAS); endpoints (OpcUaClient).
• Errors/validation: required fields, duplicate Name within list, driver-specific address format; delete confirm; list mutates only on valid commit.
• Testing: per-driver NewRow factories + Validate methods unit-tested directly; existing *FormSerializationTests extended for add/remove via the form model. Modal interaction verified manually via /run.

WS2 — Resilience typed form

• Replace the textarea in DriverResilienceSection.razor with a typed form bound to a new mutable ResilienceFormModel (all fields nullable; null = tier default): bulkhead concurrent/queue, recycle interval, and an 8-capability grid (Read, Write, Discover, Subscribe, Probe, AlarmSubscribe, AlarmAcknowledge, HistoryRead) of (timeout / retry / breaker-threshold).
• FromJson/ToJson emit only non-null overrides (blank → null, preserving the current "null = tier defaults" contract). The section gains a DriverTier parameter; each driver page passes its known tier so GetTierDefaults(tier) renders as placeholders. A collapsible "raw JSON" view remains as escape hatch.
• Errors: non-negative / sane-range numeric validation; emitted JSON must re-parse cleanly through DriverResilienceOptionsParser.
• Testing: ResilienceFormModel round-trip tests in AdminUI.Tests — blank→null, partial-override-preserved, emit→parse-back compatibility.

WS3 — Editable LDAP→role map (DB-backed, global, live on next sign-in)

• RoleGrants.razor → full CRUD over LdapGroupRoleMapping via the existing ILdapGroupRoleMappingService. Global only: IsSystemWide=true, ClusterId=null; no cluster UI. Fields: LDAP group, AdminRole (ConfigViewer/ConfigEditor/FleetAdmin), notes. A group may carry several roles (multiple rows). Edit page gated to FleetAdmin (add a minimal FleetAdmin authorization policy; confirm existing role-policy plumbing during plan-writing).
• Wire the service into LdapAuthService: at login → resolve groups → GetByGroupsAsync (indexed) → map roles → merge appsettings GroupToRole as a fallback layer (used when no DB row covers a group). Edits take effect on the user's next sign-in. DB rows authoritative + editable; appsettings entries shown read-only as "fallback."
• Errors: DB unreachable at login → catch, log, fall back to appsettings; login never blocks. CRUD: no duplicate (LdapGroup, Role); group/role required.
• Testing: extend LdapGroupRoleMappingServiceTests (in-memory EF) for CRUD + dedupe; new RoleMapper overload Map(groups, dbRows, fallbackDict) unit-tested for merge + fallback precedence + DB-error fallback.

WS4 — Cleanup (runs last, after the features exist)

• Delete stale comments: FleetStatusHub.cs ("passive channel / until the bridge lands"), EndpointRouteBuilderExtensions.cs (F15), DriverIdentitySection.razor ("Phase 4 / generic DriverEdit"), DriverEditRouter.razor + DriverTypePicker.razor (TODO(3.3/3.4) + the "falls back to legacy DriverEdit" path — verify & clean, legacy file is gone), and update DriverResilienceSection.razor's comment.
• Strip rendered notes now true: per-driver "list-editor coming in a follow-up phase" notes, the OpcUaClient endpoint note, the resilience "typed-form-ifying Polly is a follow-up" note, and the RoleGrants "UI-driven editing is deferred" note.

Cross-cutting

• No DB schema change — LdapGroupRoleMapping migration already applied; DriverConfig/ResilienceConfig columns unchanged.
• Definition of done: build clean + dotnet test green + a /run pass exercising the modal editors and role-map CRUD.
• Suggested sequence: WS1 shared shell + Modbus tags as proof → remaining drivers → WS2 → WS3 → WS4.