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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T03:01:03.373806+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.