init

enriched-qwen3-coder-next/Common/DTS.Common/Events/Sensors/SensorsList.md

@@ -0,0 +1,90 @@
+---
+source_files:
+  - Common/DTS.Common/Events/Sensors/SensorsList/SensorsListSensorSelectedEvent.cs
+  - Common/DTS.Common/Events/Sensors/SensorsList/SensorChangedEvent.cs
+generated_at: "2026-04-16T03:25:38.832250+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "58207bf6cc93d33a"
+---
+
+# SensorsList
+
+## Documentation Page: `DTS.Common.Events.Sensors.SensorsList`
+
+---
+
+### 1. Purpose  
+This module defines a set of Prism-based pub/sub events used to coordinate sensor-related state changes and user actions across the UI and business logic layers in the DTS application. Specifically, it enables decoupled communication for sensor selection, saving, updating, and modification of sensor properties (e.g., sensitivity, excitation, nonlinearity). These events allow view models and services to react to sensor lifecycle events without tight coupling—e.g., updating filter lists when a sensor is added/deleted, or refreshing sensitivity controls when a user modifies a sensor’s properties.
+
+---
+
+### 2. Public Interface  
+
+#### `SensorsListSensorSelectedEvent`  
+- **Type**: `class SensorsListSensorSelectedEvent : PubSubEvent<string[]>`  
+- **Behavior**: Publishes an array of strings (likely serial numbers or identifiers) when a sensor is selected in the sensors list UI. Subscribers receive the selected sensor identifiers via the payload.  
+- **Note**: Despite the XML comment referencing `TTSImportSummaryImportEvent` and “Import button was clicked,” the class name, namespace, and inheritance clearly indicate it is for *sensor selection*, not import. This appears to be a documentation error.
+
+#### `SensorSavedEvent`  
+- **Type**: `class SensorSavedEvent : PubSubEvent<double>`  
+- **Behavior**: Published after a new sensor is saved (e.g., added via the settings menu). The `double` payload likely represents the database ID of the newly saved sensor (as suggested by the comment referencing “FB 13120” and “save function”).
+
+#### `SensorUpdatedEvent`  
+- **Type**: `class SensorUpdatedEvent : PubSubEvent<bool>`  
+- **Behavior**: Published when a sensor is added or deleted to signal that the default filter selection in the filter list should be refreshed. The `bool` payload likely indicates whether the change was an *addition* (`true`) or *deletion* (`false`), though the source does not explicitly define the semantics of the boolean.
+
+#### `SensorChangedEvent`  
+- **Type**: `class SensorChangedEvent : PubSubEvent<SensorChangedArgs>`  
+- **Behavior**: Published when one or more sensor properties are modified by the user. Carries a `SensorChangedArgs` object detailing *which* properties changed.
+
+##### `SensorChangedArgs`  
+- **Type**: `class SensorChangedArgs`  
+- **Properties**:  
+  - `SerialNumber` (`string`) – Serial number of the changed sensor (currently unused, reserved for future use).  
+  - `DatabaseId` (`int`) – Database ID of the changed sensor (currently unused, reserved for future use).  
+  - `CurrentModelLoading` (`bool`) – `true` if the current model is being loaded (e.g., on startup or restore).  
+  - `NonLinearChanged` (`bool`) – `true` if the nonlinearity setting changed.  
+  - `SensitivityChanged` (`bool`) – `true` if the sensitivity value changed.  
+  - `IsProportionalChanged` (`bool`) – `true` if the proportionality setting changed.  
+  - `ExcitationChanged` (`bool`) – `true` if an excitation setting changed.  
+- **Constructor**:  
+  ```csharp
+  public SensorChangedArgs(string serialNumber, int databaseId, bool currentModelLoading, 
+                           bool nonLinearChanged, bool sensitivityChanged, 
+                           bool isProportionalChanged, bool excitationChanged)
+  ```
+  All parameters are required and stored immutably.
+
+---
+
+### 3. Invariants  
+- All events inherit from `Prism.Events.PubSubEvent<T>`, meaning they follow Prism’s pub/sub semantics:  
+  - Events are published asynchronously (on the UI thread by default in Prism WPF).  
+  - Subscribers must explicitly subscribe/unsubscribe to avoid memory leaks.  
+- `SensorChangedArgs` is immutable: all properties are `get`-only and initialized via constructor.  
+- The `SerialNumber` and `DatabaseId` fields in `SensorChangedArgs` are *not currently used* (per comments), so consumers should not rely on them for identification.  
+- The boolean flags in `SensorChangedArgs` are *independent*—multiple may be `true` in a single event (e.g., both `SensitivityChanged` and `ExcitationChanged` if both were modified in one operation).  
+
+---
+
+### 4. Dependencies  
+- **Internal Dependencies**:  
+  - `Prism.Events` (via `using Prism.Events;`) — required for `PubSubEvent<T>`.  
+  - Namespace `DTS.Common.Events.Sensors.SensorsList` — all events are co-located here.  
+- **External Dependencies (inferred)**:  
+  - Likely consumed by UI components (e.g., view models for sensor list, filter controls, settings panels) and services managing sensor persistence.  
+  - `SensorSavedEvent`’s `double` payload suggests integration with a database layer (e.g., returning a new sensor’s ID).  
+  - `SensorChangedEvent` implies integration with sensor configuration UI (e.g., sensitivity/excitation controls).  
+- **No external libraries beyond Prism** are referenced in the source.
+
+---
+
+### 5. Gotchas  
+- **Misleading XML comment**: `SensorsListSensorSelectedEvent`’s summary incorrectly describes `TTSImportSummaryImportEvent` and import behavior. This is likely a copy-paste error and should be corrected to reflect sensor *selection*.  
+- **Ambiguous boolean semantics**: The meaning of the `bool` payload in `SensorUpdatedEvent` is not documented beyond “used in selecting the default filter.” Consumers must infer or verify whether `true` = add, `false` = delete.  
+- **Unused fields**: `SerialNumber` and `DatabaseId` in `SensorChangedArgs` are explicitly marked as unused. Do not depend on them—future use is planned but not implemented.  
+- **No validation or error handling**: Events carry no error state or validation context. Subscribers must handle invalid states or errors independently.  
+- **No ordering guarantees**: As Prism events are asynchronous, there is no guarantee about the order in which subscribers receive events (e.g., `SensorSavedEvent` vs. `SensorUpdatedEvent` after a save operation).  
+
+None identified beyond the above.