docs(plan): design for driver-typed tag editors in the UNS TagModal (F-uns-1 / #135)
Approved design: 6 new per-driver TagConfig editor components (Modbus/S7/AbCip/AbLegacy/TwinCAT/Focas) dispatched by the selected driver's DriverType via a TagConfigEditorMap + DynamicComponent; the 3 unmapped drivers keep the generic raw-JSON editor; no raw-JSON toggle on typed drivers. Editors reuse the drivers' enums + JSON property names (not razor markup); driver pages untouched. Pure FromJson/ToJson/Validate helpers are unit-tested (no bUnit); live verify needs a non-Galaxy driver added to docker-dev. AdminUI-only, no data-model change.
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,170 @@
|
||||
# Driver-typed Tag Editors in the UNS TagModal — Design
|
||||
|
||||
**Date:** 2026-06-09
|
||||
**Task:** #135 (F-uns-1, deferred follow-up from the global-UNS feature)
|
||||
**Status:** Approved (design); pending implementation plan
|
||||
**Scope:** AdminUI only. No data-model / migration change.
|
||||
|
||||
## Goal
|
||||
|
||||
Replace the single generic raw-`TagConfig`-JSON textarea in the global UNS
|
||||
`TagModal` (`Components/Shared/Uns/TagModal.razor`) with **per-driver typed tag
|
||||
editors** that dispatch on the selected driver's `DriverType`, so an operator
|
||||
authoring an equipment-bound tag fills in driver-shaped fields
|
||||
(Modbus register/address/byte-order, S7 address, AbCip tag path, …) instead of
|
||||
hand-writing JSON.
|
||||
|
||||
This was specified at a high level in the global-UNS design
|
||||
(`docs/plans/2026-06-08-global-uns-management-design.md`, "TagModal —
|
||||
driver-typed, mirroring DriverEditRouter"). This document settles the
|
||||
implementation decisions.
|
||||
|
||||
## Decisions locked during brainstorming
|
||||
|
||||
1. **New UNS editors; reuse contracts, not markup.** Build per-driver tag-config
|
||||
editor components specifically for the TagModal. They **reuse each driver's
|
||||
enums** (`ModbusRegion`, `ModbusDataType`, …) and emit the driver's
|
||||
**camelCase JSON property names**, but do **not** reuse the driver pages'
|
||||
razor markup. The existing driver edit pages are left untouched (their field
|
||||
set differs — see §"Field mapping"). Lower risk, contained.
|
||||
2. **All 6 typed editors this pass.** Modbus, S7, AbCip, AbLegacy, TwinCAT,
|
||||
Focas each get a typed editor. OpcUaClient, Galaxy (`GalaxyMxGateway`), and
|
||||
Historian.Wonderware keep the existing generic raw-JSON editor (they have no
|
||||
tag editor in their driver pages either; Galaxy tags are browse-sourced).
|
||||
3. **No raw-JSON escape hatch on typed drivers.** Typed drivers render typed
|
||||
fields only — there is no per-modal "edit raw JSON" toggle. Consequence: each
|
||||
typed editor must cover the driver's **full curated field set** — the same
|
||||
fields the driver page's tag `EditTemplate` exposes (minus the fields the
|
||||
TagModal owns at top level). The generic textarea remains only for the 3
|
||||
unmapped drivers.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components (`Components/Shared/Uns/TagEditors/`)
|
||||
|
||||
One Razor component per typed driver:
|
||||
`ModbusTagConfigEditor.razor`, `S7TagConfigEditor.razor`,
|
||||
`AbCipTagConfigEditor.razor`, `AbLegacyTagConfigEditor.razor`,
|
||||
`TwinCATTagConfigEditor.razor`, `FocasTagConfigEditor.razor`.
|
||||
|
||||
**Component contract (convention, not a C# interface — these are components):**
|
||||
|
||||
```
|
||||
[Parameter] public string? ConfigJson { get; set; }
|
||||
[Parameter] public EventCallback<string> ConfigJsonChanged { get; set; }
|
||||
```
|
||||
|
||||
Behaviour: on `OnParametersSet`, parse `ConfigJson` → a typed working model
|
||||
(falling back to defaults on null/blank/malformed). Render the fields bound to
|
||||
the model. On any field change, serialize the model → JSON and raise
|
||||
`ConfigJsonChanged`. The TagModal binds it as `@bind-ConfigJson="_form.TagConfig"`.
|
||||
|
||||
**Pure mapping helpers.** Each editor's JSON↔model mapping lives in a pure,
|
||||
static, side-effect-free helper (e.g. `ModbusTagConfigModel.FromJson(string?)`,
|
||||
`.ToJson()`, `.Validate()`), so the (de)serialization and validation are
|
||||
unit-testable in `AdminUI.Tests` **without bUnit** (which this project lacks).
|
||||
The razor component is a thin shell over the helper.
|
||||
|
||||
### Dispatch map
|
||||
|
||||
A static `TagConfigEditorMap` — `IReadOnlyDictionary<string, Type>` keyed by
|
||||
`DriverType` (case-insensitive), mirroring `DriverEditRouter._componentMap`:
|
||||
|
||||
```
|
||||
["ModbusTcp"] = typeof(ModbusTagConfigEditor),
|
||||
["S7"] = typeof(S7TagConfigEditor),
|
||||
["AbCip"] = typeof(AbCipTagConfigEditor),
|
||||
["AbLegacy"] = typeof(AbLegacyTagConfigEditor),
|
||||
["TwinCat"] = typeof(TwinCATTagConfigEditor),
|
||||
["Focas"] = typeof(FocasTagConfigEditor),
|
||||
```
|
||||
|
||||
Drivers not in the map → the generic textarea. (Kept deliberately separate from
|
||||
`DriverEditRouter._componentMap` to avoid coupling tag editing to driver-page
|
||||
editing; both are short and stable.)
|
||||
|
||||
### TagModal integration — learning the driver type
|
||||
|
||||
- `IUnsTreeService.LoadTagDriversForEquipmentAsync` changes its return shape from
|
||||
`(string DriverInstanceId, string Display)` to
|
||||
`(string DriverInstanceId, string Display, string DriverType)`. (`UnsTreeService`
|
||||
already loads `DriverInstance`; it just projects `DriverType` too.)
|
||||
- The TagModal keeps a lookup `DriverInstanceId → DriverType` from those options
|
||||
and resolves the **currently-selected** driver's type (the driver is chosen in
|
||||
the modal's existing dropdown and can change while open).
|
||||
- Render logic in the modal body, where the raw textarea is today:
|
||||
- no driver selected → a muted "pick a driver to configure this tag" hint;
|
||||
- selected type in `TagConfigEditorMap` → `<DynamicComponent Type="…"
|
||||
Parameters="…">` passing `ConfigJson = _form.TagConfig` and a
|
||||
`ConfigJsonChanged` `EventCallback<string>` that writes back to
|
||||
`_form.TagConfig`;
|
||||
- otherwise → the existing raw `InputTextArea` over `_form.TagConfig`.
|
||||
- When the selected driver changes to a different `DriverType`, the editor swaps;
|
||||
`_form.TagConfig` carries over (a mismatched blob is simply re-parsed to
|
||||
defaults by the new editor, and the user re-enters fields).
|
||||
|
||||
## Field mapping (Tag columns vs TagConfig)
|
||||
|
||||
These stay **top-level TagModal fields** (already present): `Tag.Name`,
|
||||
`Tag.DataType` (the OPC UA type), `Tag.AccessLevel`, `Tag.WriteIdempotent`,
|
||||
`Tag.PollGroupId`.
|
||||
|
||||
`TagConfig` holds **only the driver-specific addressing/encoding fields** — the
|
||||
driver page's tag `EditTemplate` fields minus the ones the modal owns:
|
||||
|
||||
| Driver | TagConfig fields (editor) | Excluded (lives elsewhere) |
|
||||
|---|---|---|
|
||||
| Modbus (`ModbusTcp`) | region, address, dataType (wire), byteOrder, bitIndex, stringLength | name → Tag.Name; writable → AccessLevel |
|
||||
| S7 | address, stringLength | name; dataType → Tag.DataType; writable |
|
||||
| AbCip | deviceHostAddress, tagPath | name; dataType; writable |
|
||||
| AbLegacy | deviceHostAddress, address | name; dataType; writable |
|
||||
| TwinCAT | deviceHostAddress, symbolPath | name; dataType; writable |
|
||||
| Focas | deviceHostAddress, address | name; dataType; writable |
|
||||
|
||||
> Note: a driver's *wire* data type (e.g. `ModbusDataType` = how to decode the
|
||||
> register) is distinct from `Tag.DataType` (the OPC UA type) and belongs in
|
||||
> TagConfig; S7/AbCip/… have no separate wire type, so their data type is the
|
||||
> top-level `Tag.DataType` only. The exact per-driver field list is finalized in
|
||||
> the plan against each driver's tag DTO property names.
|
||||
|
||||
**Assumption / out of scope:** this assumes the runtime materialises a per-driver
|
||||
`TagDefinition` for equipment-bound tags from the `Tag` columns + `TagConfig`
|
||||
JSON. Confirming or wiring that runtime consumption is **not** part of this UI
|
||||
feature — the editors faithfully capture the driver-shaped fields under the
|
||||
driver's JSON names so the config is correct when consumed.
|
||||
|
||||
## Validation
|
||||
|
||||
Each editor helper exposes a light `Validate()` (required fields / simple ranges,
|
||||
e.g. Modbus requires an address, AbCip requires a tag path) returning an error
|
||||
string or null. The TagModal surfaces it as its existing inline error and blocks
|
||||
Save. The current "valid JSON" guard (`JsonException`) still protects the generic
|
||||
textarea path. **Server-side deploy validation remains authoritative.**
|
||||
|
||||
## Testing
|
||||
|
||||
No bUnit in this project, so:
|
||||
|
||||
- **Unit tests** (`AdminUI.Tests`, xUnit + Shouldly): each editor's
|
||||
`FromJson` / `ToJson` / `Validate` helper — round-trip fidelity, defaults on
|
||||
null/blank/malformed, property-name correctness (the emitted JSON matches the
|
||||
driver's DTO names), and validation pass/fail cases.
|
||||
- **Live verify** (docker-dev `/run`): the rig's Main cluster currently has only
|
||||
the Galaxy driver (no typed editor), so verifying a typed editor first needs a
|
||||
**non-Galaxy driver** in the rig. Steps: add a Modbus driver instance to the
|
||||
Main cluster, bind an equipment to it, open the equipment's `+ Tag` modal →
|
||||
confirm the Modbus typed fields render, fill them, Save, and inspect the
|
||||
persisted `TagConfig` JSON. Spot-check a second driver (AbCip) and confirm an
|
||||
OpcUaClient/Galaxy-bound equipment still shows the generic textarea.
|
||||
|
||||
Gate = build clean + `dotnet test` green + the docker-dev live verify above.
|
||||
|
||||
## Constraints / non-goals
|
||||
|
||||
- AdminUI only; **no** Configuration entity or migration change.
|
||||
- Driver edit pages are **not** modified (their inline tag editors stay).
|
||||
- Not changing how the runtime consumes tags; not adding fields the driver pages
|
||||
don't already expose.
|
||||
- Git safety: stage by path (never `git add .`), never stage `sql_login.txt` /
|
||||
`pki/`, never echo the gateway API key into a new tracked file, no force-push /
|
||||
no `--no-verify`.
|
||||
Reference in New Issue
Block a user