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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:21:23.908891+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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; } 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; } int GroupId { get; set; } int DASId { get; set; } 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; } int DisplayOrder { get; set; } string Position { get; set; } string TestObjectType { get; set; } 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; } string SerialNumber { get; set; } string Picture { get; set; } string DisplayName { get; set; } string Description { get; set; } bool Embedded { get; set; } DateTime LastModified { get; set; } string LastModifiedBy { get; set; } int? StaticGroupId { get; set; } 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; } int ChannelIdx { get; set; } string SensorSerialNumber { get; set; } 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(); string DisplaySerialNumber { get; } string SerialNumberConverted { get; set; } string SerialNumber { get; set; } string SerialNumberOrOriginalSerialNumber { get; } string TestObjectType { get; set; } string ParentObject { get; set; } bool SysBuilt { get; set; } string TextL1 { get; set; } string[] HardwareIds { get; set; } string Template { get; set; } void SetTemplateOnly(string value); bool LocalOnly { get; set; } string LastModifiedBy { get; set; } DateTime LastModified { get; set; } bool Embedded { get; set; } string OriginalSerialNumber { get; set; } 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.