init

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

@@ -0,0 +1,191 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Groups/GroupChannelList/IGroupChannelListView.cs
+  - Common/DTS.CommonCore/Interface/Groups/GroupChannelList/IGroupChannelSettingsListView.cs
+  - Common/DTS.CommonCore/Interface/Groups/GroupChannelList/IGroupChannelListViewModel.cs
+generated_at: "2026-04-16T02:32:21.161697+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "b48152996c8c8c44"
+---
+
+# Documentation: Group Channel List Module
+
+## 1. Purpose  
+This module defines the interfaces for the *Group Channel List* feature, which manages the display, configuration, and interaction logic for channels associated with groups or test setups in the DTS system. It serves as the abstraction layer between UI views (`IGroupChannelListView`, `IGroupChannelSettingsListView`) and the underlying data and business logic (`IGroupChannelListViewModel`). The module enables dynamic column rendering, filtering, sorting, channel management (add/remove/move), and integration with sensors, hardware, and ISO/test setup metadata—supporting both group editing and test setup editing workflows.
+
+---
+
+## 2. Public Interface  
+
+### Interfaces  
+
+#### `IGroupChannelListView`  
+*Inherits:* `IBaseView`  
+*Purpose:* Base view interface for the group channel list UI.  
+
+- **`void HandleColumns(IsoViewMode viewMode)`**  
+  Configures which columns are displayed in the channel list view based on the provided `IsoViewMode`.  
+
+#### `IGroupChannelSettingsListView`  
+*Inherits:* `IBaseView`  
+*Purpose:* View interface for the group channel *settings* panel (e.g., column configuration, filter controls).  
+
+- **`void SetOrderMode(bool bUseTestSetupOrder)`**  
+  Toggles whether channels are ordered by group order (`false`) or test setup order (`true`).  
+- **`void SetDisplayOptions(bool bShowSensorChannelUserValues)`**  
+  Controls visibility of *User Value X* columns (e.g., `UserValue1`, `UserValue2`).  
+- **`void HandleColumns(IsoViewMode viewMode)`**  
+  Same as in `IGroupChannelListView`; configures columns based on ISO view mode.  
+- **`void SetFilterMode(PossibleFilters filterMode)`**  
+  Applies a sensor-type filter (e.g., analog, digital) to determine which channel types are shown.  
+- **`int ViewDbVersion { get; set; }`**  
+  Stores the minimum client database version associated with the data in the view. Used to gate features/properties based on version compatibility.  
+
+#### `IGroupChannelListViewModel`  
+*Inherits:* `IBaseViewModel`, `IFilterableListView`  
+*Purpose:* Core logic interface coordinating views, data population, and channel operations.  
+
+- **`IGroupChannelListView View { get; set; }`**  
+  Reference to the main channel list view.  
+- **`IGroupChannelSettingsListView SettingsView { get; set; }`**  
+  Reference to the settings view.  
+- **`IDictionary<IGroup, Channels.IGroupChannel[]> PopulateChannels(...)`**  
+  Populates channels for display in views. Takes lookup dictionaries for sensors/hardware, default channel settings, and flags for admin permissions, deletion rules, and sensor push/pull behavior. Returns a mapping from groups to their channels.  
+- **`bool CreateVoltageInputChannels { get; set; }`**  
+  Controls whether dragging analog hardware onto a blank channel auto-creates voltage input channels.  
+- **`bool CompareAndMarkChannelParameters(Channels.IGroupChannel ch)`**  
+  Compares channel parameter values against the sensor database and marks differences (e.g., for UI highlighting).  
+- **`void OnSetActive()`**  
+  Hook called when the view becomes active (e.g., tab switch).  
+- **`void Unset()`**  
+  Hook called when the view is unloaded.  
+- **`void Filter(string term)`**  
+  Filters displayed channels by a text search term.  
+- **`string CapacityFormat { get; set; }`**  
+  Format string (e.g., `"N2"`) for numeric capacity values.  
+- **`List<Channels.IGroupChannel> AllChannels { get; }`**  
+  All channels *before* filtering/sorting.  
+- **`Func<IList<IChannelCode>> ChannelCodesFunc { get; }`**  
+  Lazy-loaded list of available channel codes (e.g., for dropdowns).  
+- **`ObservableCollection<Channels.IGroupChannel> Channels { get; set; }`**  
+  Channels currently displayed in the main channel list view.  
+- **`ObservableCollection<Channels.IGroupChannel> SettingChannels { get; set; }`**  
+  Snapshot of `Channels` (excluding blank channels) used in the settings view.  
+- **`bool SettingsViewLoaded { get; set; }`**  
+  Indicates whether `SettingsView` has been initialized.  
+- **`bool SettingChannelsLoaded { get; set; }`**  
+  Indicates whether `SettingChannels` UI elements have been created.  
+- **`IGroup Group { get; set; }`**  
+  The group being edited (when in group-edit mode).  
+- **`ITestSetup TestSetup { get; set; }`**  
+  The test setup being edited (when in test setup-edit mode).  
+- **`bool UseISOCodeFilterMapping { get; set; }`**  
+  If `true`, enforces strict mapping between CFC codes and ISO codes.  
+- **`void SetFilter(PossibleFilters bridgeFilter)`**  
+  Filters channels by sensor type (e.g., `PossibleFilters.Analog`, `Digital`).  
+- **`bool ShowISOCodes { get; }`**  
+  Indicates whether ISO code columns are visible.  
+- **`bool ShowUserCodes { get; }`**  
+  Indicates whether user-defined code columns are visible.  
+- **`bool ShowDallasIdColumn { get; set; }`**  
+  Controls visibility of the Dallas ID column (per case #31802).  
+- **`IsoViewMode ISOViewMode { get; set; }`**  
+  Current ISO view mode (e.g., `IsoViewMode.Standard`, `IsoViewMode.Simplified`).  
+- **`bool ShowISOStringBuilder { get; set; }`**  
+  Toggles visibility of the ISO code string builder UI.  
+- **`bool UniqueISOCodesRequired { get; set; }`**  
+  Enforces uniqueness of ISO codes.  
+- **`bool ShowChannelCodeLookupHelper { get; set; }`**  
+  Shows/hides the channel code lookup helper UI.  
+- **`bool UseTestSetupOrder { get; }`**  
+  Read-only flag indicating whether test setup ordering is active.  
+- **`bool ShowSensorChannelUserValues { get; set; }`**  
+  Controls display of user-defined value columns (mirrors `SetDisplayOptions`).  
+- **`void MoveDown(Channels.IGroupChannel[] channel)`**  
+  Moves specified channels down in the list.  
+- **`void MoveBottom(Channels.IGroupChannel[] channel)`**  
+  Moves specified channels to the bottom of the list.  
+- **`void MoveUp(Channels.IGroupChannel[] channel)`**  
+  Moves specified channels up in the list.  
+- **`void MoveTop(Channels.IGroupChannel[] channel)`**  
+  Moves specified channels to the top of the list.  
+- **`void Filter(PossibleFilters filter)`**  
+  Overload of `SetFilter` (likely for `IFilterableListView` compliance).  
+- **`void AddChannels(DragAndDropItem[] sensors)`**  
+  Adds channels for the given sensors.  
+- **`void AddChannels(IHardwareChannel[] hardwareChannels)`**  
+  Adds channels for the given hardware channels.  
+- **`void AddChannels(Channels.IGroupChannel[] groupChannels)`**  
+  Adds existing channels (e.g., copy/paste).  
+- **`void Remove(Channels.IGroupChannel channel, bool notifyChanged = true)`**  
+  Removes a channel; `notifyChanged` controls whether UI updates are triggered.  
+- **`IGroup CreateGroupIfNeeded(ITestSetup testSetup, string groupName)`**  
+  Creates a group if it doesn’t exist for the given test setup.  
+- **`void SetIncludedHardware(IDASHardware[] hardwares)`**  
+  Updates internal state to track included hardware (used for channel count display).  
+- **`bool ApplySensorDataToBlankChannels { get; set; }`**  
+  If `true`, sensor metadata (e.g., range, units) is auto-applied when dragging sensors onto blank channels.  
+- **`bool AllowChannelDeletionByNonAdminUser { get; set; }`**  
+  Controls whether non-admin users can delete channels.  
+- **`bool UserIsAdmin { get; set; }`**  
+  User role flag (admin/non-admin).  
+- **`bool AllowSensorPushAndPull { get; set; }`**  
+  Enables/disables sensor push/pull functionality.  
+- **`void SetRange(CACOption option)`**  
+  Applies a range configuration (e.g., `CACOption.Default`, `CACOption.UserDefined`) to all analog sensors.  
+- **`void Sort(object columnTag, bool bUserClick)`**  
+  Sorts channels by the specified column (e.g., `columnTag = "Name"`).  
+- **`bool ReadOnlyParametersMode { get; set; }`**  
+  Locks parameter editing (e.g., for review-only mode).  
+- **`bool ReadOnlyChannelsMode { get; set; }`**  
+  Locks channel structure edits (add/remove/move).  
+- **`int UserID { get; set; }`**  
+  ID of the current user (used for permission checks).  
+
+---
+
+## 3. Invariants  
+
+- **`Channels` vs. `SettingChannels`**: `SettingChannels` is a snapshot of `Channels` taken at `OnSetActive()`, with blank channels removed.  
+- **`ViewDbVersion` must be set before `HandleColumns`/`SetFilterMode`**: Used to gate feature availability based on client DB version.  
+- **`Group` and `TestSetup` are mutually exclusive**: Only one is non-null at a time (group-edit vs. test setup-edit mode).  
+- **`UseTestSetupOrder` is read-only**: Its value is determined internally (e.g., by `TestSetup` state) and not settable directly.  
+- **`ShowISOCodes` and `ShowUserCodes` are read-only**: Derived from configuration (e.g., `ISOViewMode`, user settings).  
+- **`AllChannels` is immutable after `PopulateChannels`**: Modifications require re-population.  
+
+---
+
+## 4. Dependencies  
+
+### Dependencies *of* this module:  
+- **`DTS.Common.Base`**: Provides `IBaseView`, `IBaseViewModel`, and `IFilterableListView`.  
+- **`DTS.Common.Enums`**: `IsoViewMode`, `PossibleFilters`.  
+- **`DTS.Common.Enums.Sensors`**: `PossibleFilters` (re-exported).  
+- **`DTS.Common.Interface.*`**:  
+  - `Channels.IGroupChannel`, `Channels.ChannelCodes.IChannelCode`  
+  - `DataRecorders.IDASHardware`, `DataRecorders.IHardwareChannel`  
+  - `Groups.GroupList.IGroup`  
+  - `Groups.GroupList.ITestSetup`  
+  - `Pagination.IPagination` (via `IFilterableListView`)  
+  - `Sensors.ISensorData`, `Sensors.SensorsList.IDragAndDropItem`  
+
+### Dependencies *on* this module:  
+- **UI Layer**: Views implementing `IGroupChannelListView`/`IGroupChannelSettingsListView` (e.g., WPF/XAML views).  
+- **Business Logic Layer**: ViewModels/controllers implementing `IGroupChannelListViewModel` (e.g., `GroupChannelListViewModel`).  
+- **Data Layer**: Services providing `sensorLookup`, `hardwareLookup`, `channelDefaults` (via `PopulateChannels`).  
+
+---
+
+## 5. Gotchas  
+
+- **`SettingChannels` is a snapshot**: Changes to `Channels` after `OnSetActive()` are *not* reflected in `SettingChannels`.  
+- **`PopulateChannels` has many flags**: Default parameters (`allowChannelDeletionByNonAdminUser`, `userIsAdmin`, etc.) imply complex permission logic; callers must explicitly set these to avoid unintended behavior.  
+- **`SetFilter` vs. `Filter(string term)`**: `SetFilter` filters by sensor type (`PossibleFilters`), while `Filter(string term)` filters by text search. Confusing naming.  
+- **`UseTestSetupOrder` is read-only**: Cannot be set directly; likely derived from `TestSetup` state (e.g., `TestSetup?.UseTestSetupOrder`).  
+- **`ShowISOCodes` is read-only**: Its value is computed (e.g., `ISOViewMode != IsoViewMode.None`), not user-configurable.  
+- **`ViewDbVersion` is critical for backward compatibility**: Must be set *before* `HandleColumns`/`SetFilterMode` to avoid UI errors with newer features.  
+- **`Move*` methods accept arrays**: Designed for multi-select operations, but behavior for overlapping/multiple calls is unspecified.  
+- **No explicit documentation on thread safety**: All methods assume UI-thread execution (common for view models).  
+
+None identified beyond the above.

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

@@ -0,0 +1,142 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Groups/GroupList/IGroupListView.cs
+  - Common/DTS.CommonCore/Interface/Groups/GroupList/TestSetupParentHelper.cs
+  - Common/DTS.CommonCore/Interface/Groups/GroupList/IGroupListViewModel.cs
+  - Common/DTS.CommonCore/Interface/Groups/GroupList/IGroup.cs
+generated_at: "2026-04-16T02:32:20.944334+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "a5d3249cf1dc850d"
+---
+
+# GroupList
+
+## Documentation: Group List Module (`DTS.Common.Interface.Groups.GroupList`)
+
+---
+
+### 1. Purpose
+
+This module defines the core interfaces and supporting types for managing *groups*—logical collections of hardware (e.g., test fixtures, sensors, data recorders)—within the DTS system. It provides a view-model abstraction (`IGroupListViewModel`) for listing, filtering, sorting, creating, editing, and deleting groups, as well as a domain interface (`IGroup`) representing an individual group’s state, metadata, and behavior (e.g., channel association, XML serialization, test setup linkage). The module serves as the data and logic layer for UI components that display and manipulate groups, decoupling presentation concerns (via `IGroupListView`) from business logic.
+
+---
+
+### 2. Public Interface
+
+#### `IGroupListView`
+- **Inherits**: `IBaseView`
+- **Purpose**: Marker interface for the view layer associated with group list UI. No additional members defined—intended for binding or dependency injection to identify group-list-specific views.
+
+#### `TestSetupParentHelper`
+- **Fields/Properties**:
+  - `int Id`
+  - `string Name { get; set; }`
+  - `bool Modified { get; set; }`
+- **Methods**:
+  - `override string ToString()` → Returns `Name`
+- **Purpose**: Simple DTO for associating test setups with a group (used in `IGroup.AssociatedTestSetups`). Likely used for UI display or tracking changes to test setup associations.
+
+#### `IGroupListViewModel`
+- **Inherits**: `IBaseViewModel`, `IFilterableListView`
+- **Properties**:
+  - `IGroupListView View { get; set; }` — Reference to the view bound to this view model.
+  - `IGroup[] Groups { get; set; }` — Current list of groups displayed/managed.
+- **Methods**:
+  - `void Unset()` — Releases resources or clears state (e.g., unsubscribes events, nulls view).
+  - `void Sort(object o, bool columnClick)` — Sorts the `Groups` collection; `o` likely specifies sort key/column; `columnClick` indicates user-initiated sort.
+  - `void OnSetActive(object page, bool groupTile, object currentUser)` — Initializes or refreshes state when the view becomes active; parameters suggest context (`page`, `groupTile` UI mode, `currentUser` permissions).
+  - `void MouseDoubleClick(int index)` — Handles double-click on group at `index` (e.g., opens editor).
+  - `void Filter(string term)` — Filters `Groups` in-place based on `term`.
+  - `IGroup GetGroup(int? id, bool updateTags = true)` — Retrieves group by ID; optionally refreshes tags.
+  - `IGroup GetGroup(string displayName)` — Retrieves group by `DisplayName`.
+  - `IGroup[] GetGroups(int[] ids)` — Bulk retrieval of groups by IDs.
+  - `IGroup[] GetAllGroups()` — Retrieves all groups (likely from persistence).
+  - `void DeleteGroups(int[] ids)` — Deletes groups by IDs.
+  - `IGroup CreateGroup()` — Creates a new, unsaved group.
+  - `IGroup CreateGroup(List<string> includedHardwareStringList)` — Creates a new group with hardware specified via legacy string IDs.
+  - `IGroup CreateGroup(SqlDataReader reader, List<string> includedHardwareStringList, List<int> dasIdList)` — Creates a group from database reader + hardware lists (likely for import/restore).
+  - `IGroup CreateGroup(IGroupDbRecord groupRecord, List<string> includedHardwareStringList, List<int> dasIdList)` — Creates a group from a database record + hardware lists.
+
+#### `IGroup`
+- **Inherits**: `IComparable<IGroup>`
+- **Properties**:
+  - `int Id`, `string Name`, `string DisplayName`, `string Description`, `bool Embedded`, `DateTime LastModified`, `string LastModifiedBy`
+  - `int? StaticGroupId` — ID of a static template group this group may derive from.
+  - `int ChannelCount`
+  - `int[] IncludedHardware` — Hardware IDs (modern scheme).
+  - `string[] IncludedHardwareStringList` — Hardware IDs in legacy `SerialNumber_type` format (used for import).
+  - `bool PositionIsMixed`, `bool PositionIsTextbox`, `bool PositionIsCombobox`, `string Position` — UI state for position field (e.g., multi-select conflict or editable).
+  - `bool TestObjectIsMixed`, `string TestObject` — UI state for test object field.
+  - `int DisplayOrder`
+  - `List<Channels.IGroupChannel> GroupChannelList` — List of channels associated with this group.
+  - `List<TestSetupParentHelper> AssociatedTestSetups` — Test setups referencing this group.
+  - `int[] TagIDs`, `string Tags` — Tag metadata.
+  - `List<string> AvailableTestObjects`, `string SelectedTestObjectItem`
+  - `List<string> AvailablePositions`, `string SelectedPositionItem`
+- **Methods**:
+  - `IGroupDbRecord GetIGroupDbRecord()` — Returns database record snapshot.
+  - `bool Filter(string term)` — Returns `true` if group matches `term` (used by `IGroupListViewModel.Filter`).
+  - `bool Save(Channels.IGroupChannel[] groupChannels, bool canUserCommitChannelCodes)` — Persists group and channels; `canUserCommitChannelCodes` likely controls validation/commit behavior.
+  - `void ClearGroupChannelSettingCache(long groupId)` — Clears cached channel settings for this group.
+  - `Channels.IGroupChannel[] GetAllChannels(bool bEditable, IDictionary<int, ISensorData> sensorLookup, IDictionary<int, IDASHardware> hardwareLookup, IChannelSetting[] channelDefaults, bool allowSensorPushAndPull = false)` — Computes/returns full channel list with resolved sensor/hardware data.
+  - `void LoadHardware()` — Populates `IncludedHardware`/`IncludedHardwareStringList` from persistence.
+  - `void ConvertToEmbedded(Channels.IGroupChannel[] groupChannels)` — Converts group to embedded mode (likely immutable).
+  - `void DeterminePositionAndTestObject(Channels.IGroupChannel[] channels)` — Infers `Position`/`TestObject` values from channels (e.g., for mixed-state detection).
+  - `ISensorData GetSensor(Channels.IGroupChannel channel, ISensorData sensorData, bool bUseIsoFilter)` — Retrieves sensor data for a channel, optionally applying ISO filter.
+  - `void SetSensor(Channels.IGroupChannel channel, ISensorData sensorData)` — Assigns sensor data to a channel.
+  - `void WriteXML(ref XmlWriter writer)` — Serializes group to XML.
+  - `IGroup ReadXML(XmlElement node, Dictionary<long, IGroupChannel> channelLookup, List<ISensorData> sensors)` — Static-like factory to deserialize group from XML.
+  - `void SetIncludedHardware(int[] hardware)` — Updates `IncludedHardware` and marks hardware as loaded.
+  - `void SetTestSetupLists()` — Populates `AssociatedTestSetups`.
+  - `bool StaticGroupIsEqual()` — Compares group to its static template (`StaticGroupId`).
+  - `bool IsDifferentThanStaticGroup { get; set; }` — Flag indicating deviation from static template.
+  - `bool TagCompatible(int[] tags)` — Checks if group’s tags intersect with `tags`.
+  - `string GetTagsAsCommaSeparatedString(TagsGetDelegate tagsGet)` — Formats tags as CSV using provided delegate for tag name lookup.
+
+---
+
+### 3. Invariants
+
+- **Group Identity**: A group’s `Id` is its primary identifier; `GetGroup(int? id)` relies on uniqueness.
+- **Hardware Consistency**: `IncludedHardware` (int array) and `IncludedHardwareStringList` (string array) must be kept in sync during import/update operations, though the string list is explicitly noted as legacy.
+- **Channel Grouping**: `GroupChannelList` must contain all channels associated with the group; `GetAllChannels` depends on this list and external lookups (`sensorLookup`, `hardwareLookup`) to resolve channel metadata.
+- **UI State Integrity**: `PositionIsMixed`, `PositionIsTextbox`, `PositionIsCombobox`, and `TestObjectIsMixed` must accurately reflect whether the group’s channels have uniform or conflicting values for `Position`/`TestObject`.
+- **Persistence Contract**: `Save` must persist both the group’s metadata (via `IGroupDbRecord`) and its channels. The `canUserCommitChannelCodes` parameter implies conditional validation (e.g., user permissions).
+- **Tag Compatibility**: `TagCompatible(int[] tags)` must return `true` if the group’s `TagIDs` has non-empty intersection with `tags`.
+
+---
+
+### 4. Dependencies
+
+#### Dependencies *of* this module:
+- **Core Interfaces**:
+  - `DTS.Common.Base.IBaseView`, `DTS.Common.Base.IBaseViewModel`, `DTS.Common.Interface.Pagination.IFilterableListView`
+  - `DTS.Common.Interface.Channels.IGroupChannel`, `Channels.IGroupChannel[]`
+  - `DTS.Common.Interface.Sensors.ISensorData`
+  - `DTS.Common.Interface.DataRecorders.IDASHardware`
+  - `DTS.Common.Interface.TestSetups.TestSetupsList.TestSetupParentHelper` (used in `IGroup.AssociatedTestSetups`)
+- **External Types**:
+  - `System.Data.SqlClient.SqlDataReader` (used in `IGroupListViewModel.CreateGroup`)
+  - `System.Xml.XmlWriter`, `System.Xml.XmlElement` (XML serialization)
+  - `System.Collections.Generic` collections (`List<T>`, `Dictionary<TKey, TValue>`)
+
+#### Dependencies *on* this module:
+- **UI Layer**: `IGroupListView` implies consumption by UI components (e.g., group list views).
+- **Persistence Layer**: `IGroupDbRecord` (referenced in `IGroup`) suggests a database abstraction layer.
+- **Channel/Sensor/Hardware Layers**: `IGroup` depends on channel, sensor, and DAS hardware interfaces for full functionality.
+- **Test Setup Module**: `TestSetupParentHelper` links to test setup management (via `AssociatedTestSetups`).
+
+---
+
+### 5. Gotchas
+
+- **Legacy Hardware IDs**: `IncludedHardwareStringList` is explicitly marked as legacy (`"primarily for import purposes"`). Mixing it with `IncludedHardware` may lead to inconsistencies if not synchronized during updates.
+- **Mixed State Flags**: Properties like `PositionIsMixed`/`TestObjectIsMixed` are *mutable* (`{ get; set; }`), but their update logic is not defined in this interface. Consumers must ensure `DeterminePositionAndTestObject` is called before relying on them.
+- **`GetAllChannels` Complexity**: This method requires multiple external lookups (`sensorLookup`, `hardwareLookup`, `channelDefaults`). Failure to provide valid dictionaries may cause runtime errors (e.g., `KeyNotFoundException`).
+- **`ReadXML` Signature Ambiguity**: `ReadXML` is an *instance method* (not static), but its behavior (e.g., whether it modifies the current instance or returns a new one) is unclear from the signature alone. The return type `IGroup` suggests it may be a factory, but this contradicts typical XML deserialization patterns.
+- **`Unset()` Semantics**: The purpose of `Unset()` is not documented. It may release resources, clear the `View` reference, or reset state—implementation-specific.
+- **`OnSetActive` Parameter Types**: Parameters `page`, `groupTile`, and `currentUser` are `object`, indicating potential use of dynamic dispatch or legacy patterns. Their expected types and usage are not specified here.
+- **`Save` Return Type**: `Save` returns `bool` but does not indicate success/failure semantics (e.g., validation failure vs. persistence failure). This is not documented in the interface.
+
+None identified beyond the above ambiguities.