init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/Realtime.md

@@ -0,0 +1,96 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannelSelectView.cs
+  - Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannelSelectViewModel.cs
+  - Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannel.cs
+generated_at: "2026-04-16T02:22:07.614992+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "1785995e6227da9e"
+---
+
+# Realtime
+
+## Documentation: Realtime Channel Selection Module
+
+### 1. Purpose  
+This module defines the foundational interfaces for a *realtime channel selection view and view model* within the DTS (Data Tracking System) architecture. It enables UI components to present and manage a selectable list of realtime data channels (e.g., sensor readings) for user interaction, supporting operations such as filtering by search text, setting the available channel list, and programmatically selecting a specific channel. It adheres to the MVVM (Model-View-ViewModel) pattern, with clear separation between the view (`IRealtimeChannelSelectView`), the view model (`IRealtimeChannelSelectViewModel`), and the underlying channel data model (`IRealtimeChannel`).
+
+### 2. Public Interface  
+
+#### `IRealtimeChannelSelectView`  
+- **Definition**: `public interface IRealtimeChannelSelectView : IBaseView`  
+- **Behavior**: A marker interface representing the *view* (UI layer) for channel selection. Inherits from `IBaseView`, implying standard view lifecycle or binding contract (e.g., `DataContext` setup, initialization hooks). No additional methods or properties are defined here—implementation details (e.g., controls, rendering) are left to concrete classes.
+
+#### `IRealtimeChannelSelectViewModel`  
+- **Definition**: `public interface IRealtimeChannelSelectViewModel : IBaseViewModel`  
+- **Behavior**: The *view model* mediating between the channel selection view and the underlying channel data.  
+  - **`ChannelSelectView`**: `IRealtimeChannelSelectView ChannelSelectView { get; set; }`  
+    Gets or sets the associated view instance. Used for view-model-to-view coordination (e.g., triggering UI updates or responding to view events).  
+  - **`SetAvailableChannels(IRealtimeChannel[] channels)`**:  
+    Updates the list of channels available for selection. The view should refresh its channel list UI to reflect this new set.  
+  - **`SetSearchText(string searchText)`**:  
+    Sets the current search/filter text. The view should filter the displayed channel list based on this text (e.g., matching `SensorName`, `ChannelName`, or other display fields).  
+  - **`SetRealtimeChannel(IRealtimeChannel channel)`**:  
+    Programmatically selects the specified channel. This likely updates the view’s active selection state and may trigger side effects (e.g., updating a details panel or starting data subscription).  
+
+#### `IRealtimeChannel`  
+- **Definition**: `public interface IRealtimeChannel`  
+- **Behavior**: Represents a single realtime data channel (e.g., a sensor reading). Provides metadata and identity for the channel.  
+  - **`Capacity`**: `double Capacity { get; }`  
+    The maximum capacity (e.g., in physical units or samples) for this channel.  
+  - **`DisplayOrder`**: `int DisplayOrder { get; }`  
+    Integer priority for sorting channels in the UI (lower values displayed first).  
+  - **`SensorName`**: `string SensorName { get; }`  
+    Human-readable name of the sensor (e.g., "Temperature Sensor A").  
+  - **`ChannelName`**: `string ChannelName { get; }`  
+    Name of the channel itself (may be distinct from `SensorName`).  
+  - **`DasNames`**: `string[] DasNames { get; }`  
+    Array of DAS (Data Acquisition System) names associated with this channel.  
+  - **`SensorSerial`**: `string SensorSerial { get; }`  
+    Serial number of the physical sensor.  
+  - **`Units`**: `string Units { get; }`  
+    Raw unit string (e.g., "V", "°C").  
+  - **`UserValue1`**: `string UserValue1 { get; }`  
+    Custom user-defined string (purpose context-dependent).  
+  - **`GroupName`**: `string GroupName { get; }`  
+    Logical group name for channel categorization (e.g., "Engine", "Hydraulics").  
+  - **`DisplayUnit`**: `string DisplayUnit { get; }`  
+    Unit string formatted for display (may differ from `Units`, e.g., "Degrees C").  
+  - **`HardwareChannelString`**: `string HardwareChannelString { get; }`  
+    Hardware-level channel identifier (e.g., "AI0", "CH3").  
+  - **`ISOCode`**: `string ISOCode { get; }`  
+    ISO-standard code for the channel (e.g., for internationalization or compliance).  
+  - **`SensorsString`**: `string SensorsString { get; }`  
+    Concatenated string of sensor identifiers (e.g., "S1,S2").  
+  - **`DasName`**: `string DasName { get; }`  
+    Single DAS name (likely the primary or first entry from `DasNames`).  
+  - **`GetId()`**: `string GetId()`  
+    Returns a unique identifier for the channel (e.g., for tracking or persistence).  
+  - **`HasPassedLevelTrigger`**: `bool HasPassedLevelTrigger { get; }`  
+    Indicates if the channel’s current value has exceeded a predefined threshold (e.g., for alerting).  
+  - **`Name`**: `string Name { get; }`  
+    Fallback display name (likely a composite of `SensorName` and `ChannelName`).  
+
+### 3. Invariants  
+- **`IRealtimeChannelSelectViewModel` must maintain a valid reference to `ChannelSelectView`** before invoking view-related operations (e.g., `SetAvailableChannels` may assume the view is attached to render updates).  
+- **`SetAvailableChannels` must be called with a non-null array** (though the array may be empty). The view model should handle null inputs gracefully (e.g., treat as an empty list), but the interface does not specify this—implementation may vary.  
+- **`SetRealtimeChannel` expects a channel from the *currently available set*** (i.e., one previously set via `SetAvailableChannels`). Passing a channel outside this set may lead to undefined behavior (e.g., selection ignored or exception).  
+- **`DisplayOrder` values must be consistent** across channels in a given selection context to ensure stable sorting. No explicit ordering guarantee is enforced by the interface, but implementations should respect this for predictable UI behavior.  
+
+### 4. Dependencies  
+- **Depends on**:  
+  - `DTS.Common.Base.IBaseView` and `DTS.Common.Base.IBaseViewModel` (via inheritance).  
+  - `DTS.Common.Interface.Realtime.IRealtimeChannel` (core data model).  
+- **Depended on by**:  
+  - Concrete implementations of `IRealtimeChannelSelectView` (e.g., WPF/WinForms user controls).  
+  - Concrete implementations of `IRealtimeChannelSelectViewModel` (e.g., business logic classes managing channel selection state).  
+  - Higher-level modules (e.g., a `RealtimeDashboardViewModel`) that compose or orchestrate channel selection workflows.  
+
+### 5. Gotchas  
+- **`DasNames` vs. `DasName`**: `DasNames` is an array, while `DasName` is a single string. Implementers must ensure `DasName` returns a consistent value (e.g., `DasNames[0]` or a primary DAS), but the interface does not specify this.  
+- **`Name` vs. `SensorName`/`ChannelName`**: `Name` is a distinct property—its value is not defined by the interface. It may be a concatenation, a fallback, or a user-editable field.  
+- **`UserValue1` semantics are undefined**: Its purpose is not documented here and may be application-specific (e.g., a user-configurable label or metadata field).  
+- **No explicit error handling**: Methods like `SetRealtimeChannel` do not specify behavior for invalid inputs (e.g., null, non-available channel). Implementations must define this.  
+- **No threading guarantees**: The interface does not specify thread-safety. Concurrent calls to `SetAvailableChannels`, `SetSearchText`, or `SetRealtimeChannel` may require external synchronization.  
+- **None identified from source alone.**