init

enriched-partialglm/Common/DTS.CommonCore/Interface/Realtime.md

@@ -0,0 +1,119 @@
+---
+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-16T12:15:17.411122+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "1785995e6227da9e"
+---
+
+# Documentation: DTS.Common.Interface.Realtime
+
+## 1. Purpose
+
+This module defines the contract for a realtime channel selection feature within a Model-View-ViewModel (MVVM) architecture. It provides three interfaces that together enable the display and selection of realtime data channels: `IRealtimeChannel` models channel metadata (sensor information, hardware identifiers, capacity), `IRealtimeChannelSelectView` represents the view abstraction, and `IRealtimeChannelSelectViewModel` defines the controller logic for managing available channels and user selection. This abstraction layer allows the realtime channel selection UI to be decoupled from concrete implementations.
+
+---
+
+## 2. Public Interface
+
+### `IRealtimeChannelSelectView`
+**Namespace:** `DTS.Common.Interface.Realtime`
+
+**Signature:**
+```csharp
+public interface IRealtimeChannelSelectView : IBaseView { }
+```
+
+A marker interface extending `IBaseView`. Defines no members of its own; exists to establish a type hierarchy for view abstraction.
+
+---
+
+### `IRealtimeChannelSelectViewModel`
+**Namespace:** `DTS.Common.Interface.Realtime`
+
+**Signature:**
+```csharp
+public interface IRealtimeChannelSelectViewModel : IBaseViewModel
+```
+
+**Properties:**
+
+| Property | Type | Access |
+|----------|------|--------|
+| `ChannelSelectView` | `IRealtimeChannelSelectView` | get; set; |
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `SetAvailableChannels` | `void SetAvailableChannels(IRealtimeChannel[] channels)` | Accepts an array of channels to populate the selection list. |
+| `SetSearchText` | `void SetSearchText(string searchText)` | Sets the current search/filter text for channel filtering. |
+| `SetRealtimeChannel` | `void SetRealtimeChannel(IRealtimeChannel channel)` | Sets the currently selected channel. |
+
+---
+
+### `IRealtimeChannel`
+**Namespace:** `DTS.Common.Interface.Realtime`
+
+**Signature:**
+```csharp
+public interface IRealtimeChannel
+```
+
+**Properties (all read-only):**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Capacity` | `double` | Numeric capacity value for the channel. |
+| `DisplayOrder` | `int` | Sort order for UI display. |
+| `SensorName` | `string` | Name of the sensor. |
+| `ChannelName` | `string` | Name of the channel. |
+| `DasNames` | `string[]` | Array of DAS (Data Acquisition System) names. |
+| `SensorSerial` | `string` | Serial identifier for the sensor. |
+| `Units` | `string` | Unit of measurement. |
+| `UserValue1` | `string` | User-defined custom value. |
+| `GroupName` | `string` | Group/category name for the channel. |
+| `DisplayUnit` | `string` | Unit string for UI display purposes. |
+| `HardwareChannelString` | `string` | Hardware identifier string. |
+| `ISOCode` | `string` | ISO standard code. |
+| `SensorsString` | `string` | String representation of sensor(s). |
+| `DasName` | `string` | Single DAS name (singular form). |
+| `Name` | `string` | General name identifier. |
+| `HasPassedLevelTrigger` | `bool` | Flag indicating if a level trigger threshold has been exceeded. |
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `GetId` | `string GetId()` | Returns a unique identifier string for the channel. |
+
+---
+
+## 3. Invariants
+
+- **View-ViewModel Binding:** `IRealtimeChannelSelectViewModel.ChannelSelectView` must reference a valid `IRealtimeChannelSelectView` instance when the view model is in use.
+- **Channel Array Handling:** `SetAvailableChannels` accepts an array; callers should handle null or empty arrays appropriately. The behavior for null arrays is not specified in the interface.
+- **Immutable Channel Data:** All properties on `IRealtimeChannel` are read-only (getters only). Implementations must provide values at construction or through other means not defined in this interface.
+- **Identifier Consistency:** The relationship between `GetId()` and `Name` is not defined by the interface; they may or may not return the same value depending on implementation.
+
+---
+
+## 4. Dependencies
+
+**This module depends on:**
+- `DTS.Common.Base` — Provides `IBaseView` and `IBaseViewModel` base interfaces that `IRealtimeChannelSelectView` and `IRealtimeChannelSelectViewModel` extend, respectively.
+
+**What depends on this module:**
+- Unknown from source alone. Concrete implementations of these interfaces, as well as consumers of the channel selection feature, would depend on this module.
+
+---
+
+## 5. Gotchas
+
+- **Singular vs. Plural DAS Names:** The interface defines both `DasName` (singular `string`) and `DasNames` (plural `string[]`). The semantic difference between these two properties is not documented in the interface; implementers and consumers should clarify whether they represent the same data in different forms or serve distinct purposes.
+- **Marker Interface:** `IRealtimeChannelSelectView` is an empty interface with no members. Its purpose appears to be purely for type identification within the `IBaseView` hierarchy.
+- **Method vs. Property for ID:** `GetId()` is defined as a method rather than a property (e.g., `Id`), which is inconsistent with the other identifier-like properties (`Name`, `ChannelName`, `SensorName`). The rationale for this design choice is not evident from the source.
+- **Search Text Behavior:** The `SetSearchText` method implies filtering capability, but the interface does not define how search text affects the available channels or whether it triggers immediate UI updates.