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

---
source_files:
  - Common/DTS.Common/Interface/Groups/IGroupImportImportView.cs
  - Common/DTS.Common/Interface/Groups/IGroupHardwareDbRecord.cs
  - Common/DTS.Common/Interface/Groups/IGroupImportOptionsView.cs
  - Common/DTS.Common/Interface/Groups/IGroupImportPreviewView.cs
  - Common/DTS.Common/Interface/Groups/ITestSetupGroupRecord.cs
  - Common/DTS.Common/Interface/Groups/IGroupChannel.cs
  - Common/DTS.Common/Interface/Groups/ITestObject.cs
  - Common/DTS.Common/Interface/Groups/IGroupDbRecord.cs
  - Common/DTS.Common/Interface/Groups/IGroupImportViewModel.cs
generated_at: "2026-04-16T03:01:03.373806+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "0340d2475dba7f20"
---

# Documentation: Group Import Module Interfaces

## 1. Purpose  
This module defines interfaces for the group import functionality, which enables users to import test groups and their associated channels from external `.grp` files into the system. It provides a layered architecture separating concerns: view interfaces for UI presentation (`IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView`), a view model (`IGroupImportViewModel`) to orchestrate interaction between views and application logic, and data interfaces representing domain entities (`IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord`, `IGroupChannel`, `ITestObject`). The module facilitates file selection, parsing, validation, preview, and committing of group data while integrating with the broader application for group creation, sensor validation, and database persistence.

## 2. Public Interface  

### Interfaces (No concrete implementations provided in source)

#### `IGroupImportImportView : IBaseView`  
- **Purpose**: Represents the view responsible for presenting progress feedback during group creation and commit operations.  
- **No additional members beyond `IBaseView`**.

#### `IGroupHardwareDbRecord`  
- **Purpose**: Describes a database record mapping hardware to a group.  
- **Properties**:  
  - `int Id { get; set; }` – Primary key of the record.  
  - `int GroupId { get; set; }` – Foreign key referencing the group.  
  - `int DASId { get; set; }` – Identifier for the data acquisition system.  
  - `string SerialNumber { get; set; }` – Serial number of the hardware device.  
- **Attributes**: `[Key]` on `Id`, `[Column("...")]` attributes map properties to DB columns.

#### `IGroupImportOptionsView : IBaseView`  
- **Purpose**: Controls file selection and validates the selection.  
- **Methods**:  
  - `bool Validate(out List<string> errors, out List<string> warnings)` – Validates selected files; returns `true` if valid, `false` otherwise. `errors` and `warnings` are populated with validation messages.

#### `IGroupImportPreviewView : IBaseView`  
- **Purpose**: Parses channels from `.grp` files, displays results, and allows group selection/renaming.  
- **Methods**:  
  - `bool Validate(bool userIsAdmin, out List<string> errors, out List<string> warnings)` – Validates selected groups (including channels and names). `errors` prevent proceeding; `warnings` are non-fatal. Returns `true` only if all selected groups are valid.

#### `ITestSetupGroupRecord`  
- **Purpose**: Describes a test setup group record in the database.  
- **Properties**:  
  - `int GroupId { get; set; }` – Database ID of the group.  
  - `int DisplayOrder { get; set; }` – Display order of the group.  
  - `string Position { get; set; }` – ISO 13499 position field (may be mixed per group).  
  - `string TestObjectType { get; set; }` – ISO 13499 test object field (may be mixed per group).  
  - `int TestSetupId { get; set; }` – ID of the parent test setup.

#### `IGroupChannel : IGroupTemplateChannel, IComparable<IGroupChannel>`  
- **Purpose**: Represents a logical channel in a group (legacy pre-2.0 test object channels).  
- **Properties**:  
  - `bool Disabled { get; set; }` – Controls whether the channel is used during data collection.  
  - `int ChannelIdx { get; set; }` – Channel index.  
  - `string SensorSerialNumber { get; set; }` – Serial number of associated sensor (if any).  
  - `string HardwareId { get; set; }` – Hardware channel identifier.  
- **Note**: Inherits from `IGroupTemplateChannel` and `IComparable<IGroupChannel>`; comparison logic not specified in source.

#### `ITestObject`  
- **Purpose**: Represents a test object (group) in the system.  
- **Properties**:  
  - `string DisplaySerialNumber { get; }` – Read-only display serial number.  
  - `string SerialNumber { get; set; }` – Current serial number.  
  - `string SerialNumberConverted { get; set; }` – Converted serial number.  
  - `string SerialNumberOrOriginalSerialNumber { get; }` – Serial number or original if current is empty.  
  - `string TestObjectType { get; set; }` – Type of test object.  
  - `string ParentObject { get; set; }` – Parent object identifier.  
  - `bool SysBuilt { get; set; }` – Whether the object is system-built.  
  - `string TextL1 { get; set; }` – L1 text label.  
  - `string[] HardwareIds { get; set; }` – Array of associated hardware IDs.  
  - `string Template { get; set; }` – Current template.  
  - `bool LocalOnly { get; set; }` – Whether the object is local-only.  
  - `string LastModifiedBy { get; set; }` – Last modifier user.  
  - `DateTime LastModified { get; set; }` – Last modification timestamp.  
  - `bool Embedded { get; set; }` – Whether the object is embedded in a test setup.  
  - `string OriginalSerialNumber { get; set; }` – Original serial number.  
  - `string OriginalTemplate { get; set; }` – Original template (preserved when embedded).  
- **Methods**:  
  - `void SortChannels()` – Sorts channels.  
  - `void SetTemplateOnly(string value)` – Sets only the template (behavior unspecified beyond signature).

#### `IGroupDbRecord`  
- **Purpose**: Describes a group record in the database.  
- **Properties**:  
  - `int Id { get; set; }` – Primary key.  
  - `string SerialNumber { get; set; }` – Group serial number.  
  - `string Picture { get; set; }` – Path or reference to group image.  
  - `string DisplayName { get; set; }` – Human-readable name.  
  - `string Description { get; set; }` – Group description.  
  - `bool Embedded { get; set; }` – Whether embedded in test setup.  
  - `DateTime LastModified { get; set; }` – Last modification timestamp.  
  - `string LastModifiedBy { get; set; }` – Last modifier user.  
  - `int? StaticGroupId { get; set; }` – Optional reference to static group ID.  
  - `string ExtraProperties { get; set; }` – Serialized extra properties.  
- **Attributes**: `[Key]` on `Id`, `[Column("...")]` attributes for DB mapping.

#### `IGroupImportViewModel : IBaseViewModel`  
- **Purpose**: Orchestrates group import flow; binds views and delegates to application services.  
- **Properties**:  
  - `IGroupImportOptionsView ImportOptionsView { get; set; }`  
  - `IGroupImportPreviewView ImportPreviewView { get; set; }`  
  - `IGroupImportImportView ImportView { get; set; }`  
  - `FileUtils.LogDelegate Logger { get; set; }` – Logging delegate.  
  - `SwitchNavStepsDelegate SwitchNavSteps { get; set; }` – Navigation step switcher.  
  - `CheckGroupExistsDelegate CheckGroupExists { get; set; }` – Group existence checker.  
  - `CheckSensorExistsDelegate CheckSensorExists { get; set; }` – Sensor existence checker.  
  - `CreateGroupDelegate CreateGroup { get; set; }` – Group creation delegate.  
  - `AddChannelToGroupDelegate AddChannel { get; set; }` – Channel addition delegate.  
  - `CommitGroupsDelegate CommitGroups { get; set; }` – Group commit delegate.  
  - `Disable_UIDelegate DisableUI { get; set; }` – UI disable delegate.  
  - `Enable_UIDelegate EnableUI { get; set; }` – UI enable delegate.  
  - `bool BrowseOk { get; set; }` – Indicates whether file browsing succeeded.  
- **Methods**:  
  - `void SetStatus(string message, Color color)` – Updates status display.  
  - `void ParseSourceFiles(string userTags)` – Parses `.grp` files; `userTags` likely metadata.  
  - `void Import()` – Commits parsed groups/channels to the application.  
  - `void Reset()` – Resets view model to initial state (reused across page visits).

### Delegates (defined in `IGroupImportViewModel.cs`)

- `SwitchNavStepsDelegate(GroupImportEnums.Steps step)` – Navigates to a new step in the import flow.  
- `CheckGroupExistsDelegate(string name)` → `bool` – Checks if a group with given serial number exists.  
- `CheckSensorExistsDelegate(string serialNumber)` → `bool` – Checks if a sensor with given serial number exists.  
- `CreateGroupDelegate(string serialNumber, string tags)` – Creates a new group with serial number and tags.  
- `AddChannelToGroupDelegate(string groupSerialNumber, string displayName, string sensorSerialNumber, double? capacity, bool? invert, string isoCode, IChannelSetting[] channelDefaults)` – Adds a channel to a group.  
- `CommitGroupsDelegate(string[] serialNumbers)` – Commits specified groups to the database.  
- `Disable_UIDelegate()` / `Enable_UIDelegate()` – UI state toggles.

## 3. Invariants  
- **`IGroupImportImportView`** must be used *only* for progress display during group commit; no validation or selection logic is part of this interface.  
- **`IGroupHardwareDbRecord`** requires `Id`, `GroupId`, `DASId`, and `SerialNumber` to be non-null/non-default for valid records (implied by `[Key]` and `[Column]` attributes).  
- **`IGroupImportOptionsView.Validate`** and **`IGroupImportPreviewView.Validate`** must populate `errors`/`warnings` even on success (no nulls); `errors` must be empty for `Validate` to return `true`.  
- **`IGroupImportPreviewView.Validate`** accepts a `userIsAdmin` flag, implying admin-specific validation rules (e.g., relaxed constraints), but behavior is not specified beyond signature.  
- **`IGroupChannel.Disabled`** directly controls data collection participation; disabled channels must be excluded from test runs.  
- **`ITestObject.Embedded`** and **`ITestObject.OriginalTemplate`** imply that embedded objects retain original template metadata; modification behavior is not specified.  
- **`IGroupImportViewModel`** delegates must be assigned before calling `ParseSourceFiles`, `Import`, or `Reset`; otherwise, runtime failures are likely (source does not specify default behavior).  

## 4. Dependencies  

### This Module Depends On:  
- **`DTS.Common.Base`** namespace (for `IBaseView`, `IBaseViewModel`).  
- **`System.ComponentModel.DataAnnotations`** and **`System.ComponentModel.DataAnnotations.Schema`** (for `IGroupHardwareDbRecord`, `IGroupDbRecord`).  
- **`DTS.Common.Interface.GroupTemplate`** (for `IGroupChannel` inheriting `IGroupTemplateChannel`).  
- **`DTS.Common.Interface.Channels`** (for `AddChannelToGroupDelegate` parameter `IChannelSetting[]`).  
- **`DTS.Common.Enums.Groups`** (for `SwitchNavStepsDelegate` parameter `GroupImportEnums.Steps`).  
- **`DTS.Common.Utils`** (for `FileUtils.LogDelegate`).  
- **`System.Windows.Media`** (for `Color` in `SetStatus`).  

### This Module Is Used By:  
- **UI layer**: Concrete implementations of `IGroupImportOptionsView`, `IGroupImportPreviewView`, `IGroupImportImportView` (e.g., WPF views).  
- **Application logic**: `IGroupImportViewModel` implementations (e.g., view model classes) that wire up delegates to application services.  
- **Data layer**: Implementations of `IGroupDbRecord`, `IGroupHardwareDbRecord`, `ITestSetupGroupRecord` (e.g., Entity Framework models).  
- **Channel/test object logic**: `IGroupChannel`, `ITestObject` implementations used during import and runtime.  

## 5. Gotchas  
- **`IGroupChannel`** is explicitly marked for *legacy* (pre-2.0) test object channels; modern channels may use a different interface (not specified here).  
- **`IGroupImportPreviewView.Validate`** uses `userIsAdmin` but does not define how admin status affects validation—implementation must infer behavior.  
- **`ITestObject.SerialNumberOrOriginalSerialNumber`** is read-only; its implementation must handle fallback logic (e.g., return `OriginalSerialNumber` if `SerialNumber` is empty), but the source does not specify.  
- **`IGroupImportViewModel.Reset()`** is required due to view model reuse across page visits; callers must ensure `Reset()` is called before reusing the instance.  
- **Delegate assignments** (e.g., `CreateGroup`, `CommitGroups`) are not validated in the interface; null delegates will cause runtime exceptions.  
- **`ExtraProperties`** in `IGroupDbRecord` is a serialized string; its format (e.g., JSON, XML) is not defined.  
- **`HardwareIds`** in `ITestObject` is an array, but `IGroupChannel.HardwareId` is a single string—implications for one-to-many hardware mapping are not documented.  
- **`ITestSetupGroupRecord.Position`** and **`TestObjectType`** may be mixed per group (per comments), but no validation or normalization is specified.  
- **`IGroupImportOptionsView.Validate`** and **`IGroupImportPreviewView.Validate`** do not specify thread-safety; UI calls must occur on the UI thread (inferred from WPF usage via `Color`).  
- **`SwitchNavStepsDelegate`** uses `GroupImportEnums.Steps`—enum values are not provided, so step ordering/validity is unknown.  

None identified beyond the above.