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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannelSelectView.cs Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannelSelectViewModel.cs Common/DTS.CommonCore/Interface/Realtime/IRealtimeChannel.cs	2026-04-16T02:22:07.614992+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.