--- 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 errors, out List 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 errors, out List 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` - **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`; 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.