diff --git a/docs/reqs/ClientRequirements.md b/docs/reqs/ClientRequirements.md index c9bd0ab..277469a 100644 --- a/docs/reqs/ClientRequirements.md +++ b/docs/reqs/ClientRequirements.md @@ -1,8 +1,10 @@ # OPC UA Client Requirements -## Overview +> **Revision** — Refreshed 2026-04-19 for the OtOpcUa v2 multi-driver platform (task #205). The Client surface (shared library + CLI + UI) shipped for v2 is preserved; this refresh restructures the document into numbered, directly-verifiable requirements (CLI-* and UI-* prefixes) layered on top of the existing detailed design content. Requirement coverage added for the `redundancy` command, alarm subscribe/ack round-trip, history-read, and UI tree-browser drag-to-subscribe behaviors. Original design-spec material for `ConnectionSettings`, `IOpcUaClientService`, models, and view-models is retained as reference-level details below the numbered requirements. -Three new .NET 10 cross-platform projects providing a shared OPC UA client library, a CLI tool, and an Avalonia desktop UI. All projects target Windows and macOS. +Parent: [HLR-001](HighLevelReqs.md#hlr-001-opc-ua-server), [HLR-009](HighLevelReqs.md#hlr-009-transport-security-and-authentication), [HLR-013](HighLevelReqs.md#hlr-013-cluster-redundancy) + +See also: `docs/Client.CLI.md`, `docs/Client.UI.md`. ## Projects @@ -10,134 +12,161 @@ Three new .NET 10 cross-platform projects providing a shared OPC UA client libra |---------|------|---------| | `ZB.MOM.WW.OtOpcUa.Client.Shared` | Class library | Core OPC UA client, models, interfaces | | `ZB.MOM.WW.OtOpcUa.Client.CLI` | Console app | Command-line interface using CliFx | -| `ZB.MOM.WW.OtOpcUa.Client.UI` | Avalonia app | Desktop UI with tree browser, subscriptions, alarms | -| `ZB.MOM.WW.OtOpcUa.Client.Shared.Tests` | Test project | Unit tests for shared library | -| `ZB.MOM.WW.OtOpcUa.Client.CLI.Tests` | Test project | Unit tests for CLI commands | -| `ZB.MOM.WW.OtOpcUa.Client.UI.Tests` | Test project | Unit tests for UI view models | +| `ZB.MOM.WW.OtOpcUa.Client.UI` | Avalonia app | Desktop UI | +| `ZB.MOM.WW.OtOpcUa.Client.Shared.Tests` | Test project | Shared-library unit tests | +| `ZB.MOM.WW.OtOpcUa.Client.CLI.Tests` | Test project | CLI command tests | +| `ZB.MOM.WW.OtOpcUa.Client.UI.Tests` | Test project | ViewModel unit tests | + +## Shared Requirements (Client.Shared) + +### SHR-001: Single Service Interface + +The Client.Shared library shall expose a single service interface `IOpcUaClientService` covering connect, disconnect, read, write, browse, subscribe, alarm-subscribe, alarm-ack, history-read-raw, history-read-aggregate, and get-redundancy-info operations. + +### SHR-002: ConnectionSettings Model + +The library shall expose a `ConnectionSettings` record with the fields: `EndpointUrl` (required), `FailoverUrls[]`, `Username`, `Password`, `SecurityMode` (None/Sign/SignAndEncrypt; default None), `SessionTimeoutSeconds` (default 60), `AutoAcceptCertificates` (default true), `CertificateStorePath`. + +### SHR-003: Automatic Failover + +The library shall monitor session keep-alive and automatically fail over across `FailoverUrls` when the primary endpoint is unreachable, emitting a `ConnectionStateChanged` event on each transition (Disconnected / Connecting / Connected / Reconnecting). + +### SHR-004: Cross-Platform Certificate Store + +The library shall auto-generate a client certificate on first use and store it in a cross-platform path (default `{AppData}/OtOpcUaClient/pki/`). Server certificates are auto-accepted when `AutoAcceptCertificates = true`. + +### SHR-005: Type-Coercing Write + +The library's `WriteValueAsync(NodeId, object)` shall read the node's current value to determine target type and coerce the input value before sending. + +### SHR-006: UI-Thread Dispatch Neutrality + +The library shall not assume any specific synchronization context. Events (`DataChanged`, `AlarmEvent`, `ConnectionStateChanged`) are raised on the OPC UA stack thread; the consuming CLI / UI is responsible for dispatching to its UI thread. + +--- + +## CLI Requirements (Client.CLI) + +### CLI-001: Command Surface + +The CLI shall expose the following commands: `connect`, `read`, `write`, `browse`, `subscribe`, `historyread`, `alarms`, `redundancy`. + +### CLI-002: Common Options + +All CLI commands shall accept the options `-u, --url` (required), `-U, --username`, `-P, --password`, `-S, --security none|sign|encrypt`, `-F, --failover-urls` (comma-separated), `--verbose`. + +### CLI-003: Connect Command + +The `connect` command shall attempt to establish a session using the supplied options and print `Connected` plus the resolved endpoint's `ServerUriArray` and `ApplicationUri` on success, or a diagnostic error message on failure. + +### CLI-004: Read Command + +The `read -n ` command shall print `NodeId`, `Value`, `StatusCode`, `SourceTimestamp`, `ServerTimestamp` one per line. + +### CLI-005: Write Command + +The `write -n -v ` command shall coerce the value to the node's current type (per SHR-005) and print the resulting `StatusCode`. A `Bad_UserAccessDenied` result is printed verbatim so operators see the authorization outcome. + +### CLI-006: Browse Command + +The `browse [-n ] [-r] [-d ]` command shall list child nodes under `parent` (or the `Objects` folder if omitted). `-r` enables recursion up to `-d` depth (default 1). + +### CLI-007: Subscribe Command + +The `subscribe -n -i ` command shall create a monitored item at `intervalMs` publishing interval, print each `DataChanged` event as ` ` until Ctrl-C, then cleanly unsubscribe. + +### CLI-008: Historyread Command + +The `historyread -n --start --end [--max ] [--aggregate --interval ]` command shall print raw values or aggregate buckets. Supported aggregate types: Average, Minimum, Maximum, Count, Start, End. + +### CLI-009: Alarms Command + +The `alarms [-n ] [-i ]` command shall subscribe to alarm events, print each event as `