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

---
source_files:
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportImportView.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupHardwareDbRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportOptionsView.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportPreviewView.cs
  - Common/DTS.CommonCore/Interface/Groups/ITestSetupGroupRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupChannel.cs
  - Common/DTS.CommonCore/Interface/Groups/ITestObject.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupDbRecord.cs
  - Common/DTS.CommonCore/Interface/Groups/IGroupImportViewModel.cs
generated_at: "2026-04-16T02:21:23.908891+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "0073692ccbf88d7d"
---

# Groups

## Documentation: Group Import Module Interfaces

---

### 1. **Purpose**

This module defines a set of interfaces that constitute the *Group Import* subsystem, responsible for importing test groups (and their associated channels) from external `.grp` files into the application. It supports a multi-step workflow: selecting source files (`IGroupImportOptionsView`), previewing and validating parsed groups/channels (`IGroupImportPreviewView`), and committing the groups to the system while reporting progress (`IGroupImportImportView`). The module is decoupled from UI implementation via view interfaces and delegates, enabling separation of concerns and testability. It interacts with core domain entities like `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`, `IGroupChannel`, and `ITestObject`, and relies on external services (e.g., group/sensor existence checks, group creation, database commit) provided via delegate injection.

---

### 2. **Public Interface**

#### Interfaces (View Layer)

| Interface | Method/Property | Signature | Description |
|-----------|-----------------|-----------|-------------|
| `IGroupImportImportView` | — | *N/A* | Marker interface (extends `IBaseView`) for the view responsible for displaying progress during group creation and commit. |
| `IGroupImportOptionsView` | `Validate` | `bool Validate(out List<string> errors, out List<string> warnings);` | Validates file selection. Returns `true` if files are selected; `false` otherwise. Populates `errors` and `warnings` with validation messages. |
| `IGroupImportPreviewView` | `Validate` | `bool Validate(bool userIsAdmin, out List<string> errors, out List<string> warnings);` | Validates selected groups (including channels and group names). `userIsAdmin` may affect validation rules. Returns `true` only if *all* selected groups are valid. Errors prevent proceeding; warnings are non-fatal. |
| `IGroupImportViewModel` | `SetStatus` | `void SetStatus(string message, Color color);` | Sets status message and associated color (e.g., for UI feedback). |
| | `ImportOptionsView` | `IGroupImportOptionsView ImportOptionsView { get; set; }` | Gets/sets the options view (file selection & validation). |
| | `ImportPreviewView` | `IGroupImportPreviewView ImportPreviewView { get; set; }` | Gets/sets the preview view (group/channel parsing & selection). |
| | `ImportView` | `IGroupImportImportView ImportView { get; set; }` | Gets/sets the import progress view. |
| | `ParseSourceFiles` | `void ParseSourceFiles(string userTags);` | Reads and parses source `.grp` files, extracting groups and channels. `userTags` are applied during parsing. |
| | `Import` | `void Import();` | Commits parsed groups and channels to the application. |
| | `Reset` | `void Reset();` | Resets the view model to initial state (re-initialization for page reuse). |
| | `Logger` | `FileUtils.LogDelegate Logger { get; set; }` | Logging delegate for internal messages. |
| | `SwitchNavSteps` | `SwitchNavStepsDelegate SwitchNavSteps { get; set; }` | Delegate to navigate to another step in the application. |
| | `CheckGroupExists` | `CheckGroupExistsDelegate CheckGroupExists { get; set; }` | Delegate to check if a group (by serial number) exists. |
| | `CheckSensorExists` | `CheckSensorExistsDelegate CheckSensorExists { get; set; }` | Delegate to check if a sensor (by serial number) exists. |
| | `CreateGroup` | `CreateGroupDelegate CreateGroup { get; set; }` | Delegate to create a new group (by serial number and tags). |
| | `AddChannel` | `AddChannelToGroupDelegate AddChannel { get; set; }` | Delegate to add a channel to a group (with optional overrides for capacity, invert, ISO code, and defaults). |
| | `CommitGroups` | `CommitGroupsDelegate CommitGroups { get; set; }` | Delegate to commit one or more groups to the database. |
| | `DisableUI` / `EnableUI` | `Disable_UIDelegate DisableUI { get; set; }`<br>`Enable_UIDelegate EnableUI { get; set; }` | Delegates to disable/enable the UI during long-running operations. |
| | `BrowseOk` | `bool BrowseOk { get; set; }` | Indicates whether the file browse operation succeeded (likely used internally). |

#### Domain Record Interfaces

| Interface | Property | Signature | Description |
|-----------|----------|-----------|-------------|
| `IGroupHardwareDbRecord` | `Id`, `GroupId`, `DASId`, `SerialNumber` | `int Id { get; set; }`<br>`int GroupId { get; set; }`<br>`int DASId { get; set; }`<br>`string SerialNumber { get; set; }` | Represents a hardware mapping record in the DB: links a group (`GroupId`) to a DAS (`DASId`) and hardware serial number. |
| `ITestSetupGroupRecord` | `GroupId`, `DisplayOrder`, `Position`, `TestObjectType`, `TestSetupId` | `int GroupId { get; set; }`<br>`int DisplayOrder { get; set; }`<br>`string Position { get; set; }`<br>`string TestObjectType { get; set; }`<br>`int TestSetupId { get; set; }` | Represents a test setup group record in the DB. Includes ISO 13499 fields (`Position`, `TestObjectType`). Groups may contain mixed values. |
| `IGroupDbRecord` | `Id`, `SerialNumber`, `Picture`, `DisplayName`, `Description`, `Embedded`, `LastModified`, `LastModifiedBy`, `StaticGroupId`, `ExtraProperties` | `int Id { get; set; }`<br>`string SerialNumber { get; set; }`<br>`string Picture { get; set; }`<br>`string DisplayName { get; set; }`<br>`string Description { get; set; }`<br>`bool Embedded { get; set; }`<br>`DateTime LastModified { get; set; }`<br>`string LastModifiedBy { get; set; }`<br>`int? StaticGroupId { get; set; }`<br>`string ExtraProperties { get; set; }` | Represents a group entity in the DB. Includes metadata (display name, description, picture), timestamps, and extensibility (`ExtraProperties`). |

#### Channel & Test Object Interfaces

| Interface | Property/Method | Signature | Description |
|-----------|-----------------|-----------|-------------|
| `IGroupChannel` | `Disabled`, `ChannelIdx`, `SensorSerialNumber`, `HardwareId` | `bool Disabled { get; set; }`<br>`int ChannelIdx { get; set; }`<br>`string SensorSerialNumber { get; set; }`<br>`string HardwareId { get; set; }` | Logical channel in a group. `Disabled` excludes it from data collection. Extends `IGroupTemplateChannel` and `IComparable<IGroupChannel>`. |
| `ITestObject` | `SortChannels()`, `DisplaySerialNumber`, `SerialNumberConverted`, `SerialNumber`, `SerialNumberOrOriginalSerialNumber`, `TestObjectType`, `ParentObject`, `SysBuilt`, `TextL1`, `HardwareIds`, `Template`, `SetTemplateOnly`, `LocalOnly`, `LastModifiedBy`, `LastModified`, `Embedded`, `OriginalSerialNumber`, `OriginalTemplate` | `void SortChannels();`<br>`string DisplaySerialNumber { get; }`<br>`string SerialNumberConverted { get; set; }`<br>`string SerialNumber { get; set; }`<br>`string SerialNumberOrOriginalSerialNumber { get; }`<br>`string TestObjectType { get; set; }`<br>`string ParentObject { get; set; }`<br>`bool SysBuilt { get; set; }`<br>`string TextL1 { get; set; }`<br>`string[] HardwareIds { get; set; }`<br>`string Template { get; set; }`<br>`void SetTemplateOnly(string value);`<br>`bool LocalOnly { get; set; }`<br>`string LastModifiedBy { get; set; }`<br>`DateTime LastModified { get; set; }`<br>`bool Embedded { get; set; }`<br>`string OriginalSerialNumber { get; set; }`<br>`string OriginalTemplate { get; set; }` | Represents a test object (group) in the application. Supports serial number variants, template embedding, and hardware ID tracking. |

#### Delegates

| Delegate | Signature | Purpose |
|----------|-----------|---------|
| `SwitchNavStepsDelegate` | `void (GroupImportEnums.Steps step)` | Navigate to a different application step. |
| `CheckGroupExistsDelegate` | `bool (string name)` | Check if a group (by serial number/name) exists. |
| `CheckSensorExistsDelegate` | `bool (string serialNumber)` | Check if a sensor (by serial number) exists. |
| `CreateGroupDelegate` | `void (string serialNumber, string tags)` | Create a new group with given serial number and tags. |
| `AddChannelToGroupDelegate` | `void (string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` | Add a channel to a group. `capacity`/`invert` override sensor defaults if non-null. |
| `CommitGroupsDelegate` | `void (string[] serialNumbers)` | Commit groups (by serial numbers) to the database. |
| `Disable_UIDelegate` / `Enable_UIDelegate` | `void ()` | Disable/enable the UI. |

---

### 3. **Invariants**

- **`IGroupImportOptionsView.Validate`**: Must return `true` *only* if files have been selected. Validation errors/warnings must be non-null outputs (even if empty lists).
- **`IGroupImportPreviewView.Validate`**: Must return `true` *only* if *all* selected groups are valid (no errors). Warnings do not affect return value. Admin status (`userIsAdmin`) may influence validation rules.
- **`IGroupChannel.Disabled`**: When `true`, the channel must be excluded from data collection during test runs.
- **`IGroupDbRecord.Embedded`**: Indicates whether the group is embedded in a test setup (likely immutable after embedding).
- **`ITestObject.Embedded` / `ITestObject.OriginalTemplate`**: When a group is embedded, its `Template` may change, but `OriginalTemplate` preserves the pre-embedding value.
- **`IGroupHardwareDbRecord`**: Each record uniquely maps a `GroupId` → `DASId` + `SerialNumber`. No constraints on uniqueness of `DASId` or `SerialNumber` across records are specified.

---

### 4. **Dependencies**

#### Module Dependencies (from source):
- **Base Layer**: `DTS.Common.Base` (`IBaseView`, `IBaseViewModel`)
- **Enums**: `DTS.Common.Enums.Groups.GroupImportEnums.Steps` (used in `SwitchNavStepsDelegate`)
- **Utils**: `FileUtils.LogDelegate` (for logging)
- **Channels**: `DTS.Common.Interface.Channels.IChannelSetting[]` (used in `AddChannelToGroupDelegate`)
- **GroupTemplate**: `IGroupTemplateChannel` (base interface for `IGroupChannel`)

#### Dependencies *on* this Module:
- **UI Layer**: Concrete implementations of `IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView`, and `IGroupImportViewModel`.
- **Application Core**: Must provide implementations for the delegates (`CheckGroupExists`, `CreateGroup`, `AddChannel`, `CommitGroups`, etc.) to integrate with the broader system (DB, sensor/group registries, navigation).

#### Inferred Dependencies:
- `DTS.Common.Interface.GroupTemplate` (for `IGroupTemplateChannel`).
- Database access layer (for `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`).
- Sensor and group registries (for `CheckGroupExists`, `CheckSensorExists`).

---

### 5. **Gotchas**

- **`IGroupChannel` is marked for *legacy* use**: The XML comment explicitly states: *"THIS IS FOR THE OLD (PRE 2.0) TESTOBJECT CHANNELS"*. New implementations may use a different channel model.
- **`ITestObject` has redundant serial number properties**: `SerialNumber`, `OriginalSerialNumber`, `SerialNumberConverted`, and `SerialNumberOrOriginalSerialNumber` suggest complex serial number handling (e.g., conversion, fallback logic). Behavior of these properties is not fully specified.
- **`IGroupImportPreviewView.Validate` admin flag**: The `userIsAdmin` parameter implies role-based validation rules, but the source does not specify how admin/non-admin behavior differs.
- **`IGroupImportViewModel` re-use pattern**: The `Reset()` method exists because the view model is reused across page visits (not recreated). This may lead to state leakage if `Reset()` is incomplete or skipped.
- **`AddChannelToGroupDelegate` parameters**: `capacity`/`invert` are nullable; null means "use sensor defaults". This is critical for correct channel configuration.
- **`IGroupHardwareDbRecord` field names**: Uses `DASId` (not `HardwareId` or `DeviceId`), suggesting a specific hardware abstraction layer (DAS = Data Acquisition System?).
- **No validation rules for group names/serial numbers**: The interfaces do not define naming constraints (e.g., uniqueness, allowed characters), though `CheckGroupExists` implies uniqueness enforcement elsewhere.

*None identified beyond the above.*