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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Classes/Groups/GroupGRPImportError.cs Common/DTS.Common/Classes/Groups/GroupGRPImportGroup.cs Common/DTS.Common/Classes/Groups/GroupHardwareDbRecord.cs Common/DTS.Common/Classes/Groups/TestSetupGroupRecord.cs Common/DTS.Common/Classes/Groups/GroupDbRecord.cs Common/DTS.Common/Classes/Groups/GroupGRPImportChannel.cs Common/DTS.Common/Classes/Groups/ChannelDbRecord.cs Common/DTS.Common/Classes/Groups/GroupHelper.cs	2026-04-16T03:16:28.845582+00:00	Qwen/Qwen3-Coder-Next-FP8	1	b79a1cdde998f5b5

Documentation: Groups Module

1. Purpose

This module provides data structures and helper utilities for representing, importing, and managing group-based test configurations—specifically those sourced from .GRP files (TDC format)—and their persistence in the database. It defines import-time models (GroupGRPImportGroup, GroupGRPImportChannel, GroupGRPImportError) for parsing and validating .GRP files, database record models (GroupDbRecord, GroupHardwareDbRecord, TestSetupGroupRecord, ChannelDbRecord) for ORM-style data access, and a static GroupHelper class to cache and manage cross-referenced metadata (e.g., static group names, DAS IDs, channel-group mappings) during runtime. The module serves as the canonical data model layer for group-centric test setups in the DTS system.

2. Public Interface

GroupGRPImportError

• Errors enum: Defines all possible error codes during .GRP file import:
  • FileEmpty, InvalidISOCodeInput, InvalidFullScaleInput, InvalidSensorInput, InvalidInvertInput, SensorNotFound, InvalidInputMode, InvalidDefaultValue, InvalidActiveValue, InvalidFireMode, InvalidDelay, InvalidLimitDuration, InvalidDuration, InvalidCurrent
• Properties:
  • Errors ErrorCode { get; set; }: The specific error encountered.
  • string File { get; set; }: Path or name of the .GRP file where the error occurred.
  • int Line { get; set; }: Line number in the file where the error occurred.
  • string ExtraInfo { get; set; }: Human-readable error details.
• override string ToString(): Returns ExtraInfo.

GroupGRPImportGroup

• Properties:
  • bool Included { get; set; } = true: Whether the group is included in the current import operation.
  • bool Overwrite { get; set; } = true: Whether existing group data should be overwritten.
  • string GroupName { get; set; }: Name of the group.
  • string GroupTags { get; set; }: Tags associated with the group.
  • string ImportingUserTags { get; set; }: User-provided tags during import.
  • string SourceFile { get; set; }: Path to the source .GRP file.
  • GroupGRPImportChannel[] Channels { get; set; } = { }: Array of imported channels.
  • GroupGRPImportError[] GroupErrors { get; set; } = null: Array of errors encountered during import of the entire group.
  • bool GroupNameHasError { get; set; }: UI hint indicating if the group name field has an error (used for visual feedback).

GroupHardwareDbRecord

• Implements: IGroupHardwareDbRecord
• Properties:
  • int Id { get; set; }: Primary key (database ID).
  • int GroupId { get; set; }: Foreign key to Group table.
  • int DASId { get; set; }: Foreign key to DAS (Data Acquisition System) record.
  • string SerialNumber { get; set; }: Serial number of hardware associated with the group.
• Constructors:
  • GroupHardwareDbRecord(): Default constructor.
  • GroupHardwareDbRecord(IGroupHardwareDbRecord copy): Copy constructor.
  • GroupHardwareDbRecord(IDataReader reader): Populates from database reader.

TestSetupGroupRecord

• Implements: ITestSetupGroupRecord
• Properties:
  • int GroupId { get; set; }: Foreign key to group.
  • int DisplayOrder { get; set; }: Order in which the group appears in a test setup UI.
  • string Position { get; set; }: ISO 13499 position field.
  • string TestObjectType { get; set; }: ISO 13499 test object field.
  • int TestSetupId { get; set; }: Foreign key to test setup.
• Constructors:
  • TestSetupGroupRecord(): Default constructor.
  • TestSetupGroupRecord(IDataReader reader): Populates from database reader.
  • TestSetupGroupRecord(ITestSetupGroupRecord copy): Copy constructor.

GroupDbRecord

• Implements: IGroupDbRecord
• Properties:
  • int Id { get; set; }: Primary key (database ID).
  • string SerialNumber { get; set; }: Serial number (used as group identifier).
  • string Picture { get; set; }: Path or identifier for group image.
  • string DisplayName { get; set; }: Human-readable name.
  • string Description { get; set; }: Group description.
  • bool Embedded { get; set; }: Whether the group is embedded (system-managed).
  • DateTime LastModified { get; set; }: Timestamp of last modification.
  • string LastModifiedBy { get; set; }: User who last modified the group.
  • int? StaticGroupId { get; set; }: Reference to static group ID if applicable.
  • string ExtraProperties { get; set; }: Serialized JSON of additional properties.
• Constructors:
  • GroupDbRecord(): Default constructor.
  • GroupDbRecord(IGroupDbRecord copy): Copy constructor.
  • GroupDbRecord(IGroup copy, List<KeyValuePair<string, string>> extraProperties): Converts from domain IGroup model.
  • GroupDbRecord(IDataReader reader): Populates from database reader.

GroupGRPImportChannel

• Constants:
  • SerialNumberField = 0, DisplayNameField = 1, ISOCodeField = 2, InvertField = 3, CapacityField = 4, InputModeField = 5, DefaultValueField = 6, ActiveValueField = 7, FireModeField = 8, DelayField = 9, LimitDurationField = 10, DurationField = 11, CurrentField = 12: Field indices for parsing .GRP files.
• Properties:
  • string SensorSerialNumber { get; set; }: Serial number of the sensor.
  • string DisplayName { get; set; }: Channel display name.
  • string ISOCode { get; set; }: ISO-compliant channel code.
  • bool Invert { get; set; }: Whether the channel signal is inverted.
  • double FullScale { get; set; }: Full-scale value (e.g., for analog channels).
  • InputModes? InputMode { get; set; } = null: Input mode (see enum below).
  • FireModes? FireMode { get; set; } = null: Fire mode (see enum below).
  • double? DefaultValue { get; set; } = null: Default value (e.g., for analog channels).
  • double? ActiveValue { get; set; } = null: Active value (e.g., trigger threshold).
  • double? Delay { get; set; } = null: Delay before firing (seconds).
  • bool? LimitDuration { get; set; } = null: Whether duration is limited.
  • double? Duration { get; set; } = null: Duration of fire pulse (seconds).
  • double? Current { get; set; } = null: Current limit for squib firing.
  • GroupGRPImportError Error { get; set; } = null: Channel-specific import error.
  • GroupGRPImportGroup ParentGroup { get; set; }: Parent group reference.
  • string GroupName { get; }: Derived from ParentGroup.GroupName; returns "---" if no parent.
• Nested Enums:
  • InputModes: na, TLH, THL, CCNO, CCNC
  • FireModes: na, CD, CC
• Constants:
  • DefaultInputMode = InputModes.CCNO
  • DefaultFireMode = FireModes.CD
  • DefaultDefaultValue = 0.0, DefaultActiveValue = 1.0, DefaultDelay = 0.00, DefaultLimitDuration = true, DefaultDuration = 10.0, DefaultCurrent = 1.5
• Methods:
  • void GroupNameInvalidate(): Forces UI refresh for GroupName binding.

ChannelDbRecord

• Implements: IChannelDbRecord
• Properties:
  • long Id { get; set; }: Primary key (database ID).
  • int GroupId { get; set; }: Foreign key to group.
  • string IsoCode { get; set; }: ISO channel code.
  • string IsoChannelName { get; set; }: ISO-compliant channel name.
  • string UserCode { get; set; }: User-defined channel code.
  • string UserChannelName { get; set; }: User-defined channel name.
  • int DASId { get; set; }: Foreign key to DAS.
  • int DASChannelIndex { get; set; }: Channel index on the DAS.
  • int GroupChannelOrder { get; set; }: Order within the group.
  • int TestSetupOrder { get; set; }: Order within a test setup.
  • int SensorId { get; set; }: Foreign key to sensor.
  • bool Disabled { get; set; }: Whether channel is disabled.
  • bool IsDisabled { get; set; }: Backward-compatible alias for Disabled.
  • DateTime LastModified { get; set; }: Timestamp of last modification.
  • string LastModifiedBy { get; set; }: User who last modified the channel.
• Constructors:
  • ChannelDbRecord(): Default constructor.
  • ChannelDbRecord(IChannelDbRecord copy): Copy constructor.
  • ChannelDbRecord(IDataReader reader): Populates from database reader.

GroupHelper

• Static utility class (abstract, non-instantiable).
• Methods:
  • ClearStaticGroupNames(), SetStaticGroupName(int id, string name), GetStaticGroupName(int id): Manage mapping of static group IDs to names.
  • ClearEmbeddedGroupIdList(), SetEmbeddedGroupId(int id), IsGroupEmbedded(int id): Manage list of embedded group IDs.
  • ClearTestSetupGroupIds(), SetTestSetupGroupId(int groupId, int testSetupId), GetTestSetupGroupId(int groupId): Map group IDs to test setup IDs.
  • ClearGroupChannelIds(), AddGroupChannelId(int sensorId, int groupId), GetGroupIdsFromChannels(int sensorId): Map sensor IDs to associated group IDs.
  • ClearDASIds(), SetDASId(string serialNumber, int dasId), GetDASId(string serialNumber): Map DAS serial numbers to database IDs.
  • ClearBaseModuleChannelIndexList(), SetBaseModuleChannelIndexList(...), GetChannelIndexes(...): Manage channel index mappings for base/module serial number pairs.
  • ClearDASIdChannelIndexGroupIdList(), SetDASIdChannelIndexGroupIdList(...), GetGroupIds(...): Map DAS ID + channel index → group ID.
  • ClearTestSetupHardwareIds(), AddTestSetupHardwareId(int dasId, int testSetupId), GetTestSetupHardwareIds(int DASId): Map DAS IDs to associated test setup IDs.
  • ClearGroupHardwareIds(), AddGroupHardwareId(int dasId, int groupId), GetGroupHardwareIds(int DASId): Map DAS IDs to associated group IDs.

3. Invariants

• GroupGRPImportGroup.Channels: Always initialized to an empty array ({ }), never null.
• GroupGRPImportGroup.GroupErrors: Initialized to null by default; non-null only if errors occurred during import.
• GroupGRPImportChannel.* nullable properties (e.g., InputMode, DefaultValue, FireMode, etc.): May be null if not specified in the .GRP file; default values are defined as constants (e.g., DefaultInputMode, DefaultFireMode, etc.).
• GroupDbRecord.ExtraProperties: Serialized as JSON using JavaScriptSerializer; deserialization responsibility lies with consumers.
• ChannelDbRecord.IsDisabled: Redirects to Disabled; both properties must be kept in sync when set via IsDisabled.
• GroupHelper static caches: Must be cleared between operations (e.g., import sessions) to avoid stale data; no automatic cleanup is provided.

4. Dependencies

Dependencies of this module:

• DTS.Common.Base: Base classes (BasePropertyChanged) used by GroupGRPImportGroup, GroupGRPImportChannel, GroupHardwareDbRecord, TestSetupGroupRecord, GroupDbRecord, ChannelDbRecord.
• DTS.Common.Interface.Groups: Interfaces IGroupHardwareDbRecord, ITestSetupGroupRecord, IGroupDbRecord.
• DTS.Common.Interface.Channels: Interface IChannelDbRecord.
• System.Data: IDataReader used in record constructors.
• System.ComponentModel.DataAnnotations: [Key] attribute on Id fields.
• System.Web.Script.Serialization.JavaScriptSerializer: Used in GroupDbRecord constructor to serialize ExtraProperties.

Dependencies on this module:

• Import/Export logic: .GRP file parsing and validation (not included here, but inferred from GroupGRPImport* classes).
• Database layer: GroupDbRecord, ChannelDbRecord, GroupHardwareDbRecord, TestSetupGroupRecord are used by data access layers.
• UI layer: GroupGRPImportGroup.GroupNameHasError and GroupGRPImportChannel.GroupName suggest binding to UI controls (e.g., textboxes, error indicators).
• Runtime metadata management: GroupHelper is used by other modules to resolve IDs, serial numbers, and mappings without repeated DB queries.

5. Gotchas

• GroupGRPImportChannel.GroupName is a computed property: It returns ParentGroup.GroupName or "---" if ParentGroup is null. UI bindings must be manually invalidated via GroupNameInvalidate() if ParentGroup changes after construction.
• IsDisabled alias in ChannelDbRecord: While IsDisabled redirects to Disabled, setting IsDisabled only raises OnPropertyChanged("IsDisabled"), not "Disabled". This may cause UI binding inconsistencies if consumers bind to "Disabled" directly.
• GroupDbRecord.ExtraProperties serialization: Uses legacy JavaScriptSerializer; not compatible with modern System.Text.Json. Consumers must use the same serializer for round-tripping.
• GroupHelper static state: Caches are global and mutable; failure to call Clear*() methods between operations (e.g., import sessions) can lead to incorrect ID lookups or stale mappings.
• GroupHardwareDbRecord.Id vs GroupDbRecord.Id: Both use int Id, but ChannelDbRecord.Id uses long Id. Ensure correct type usage in queries.
• GroupGRPImportGroup.GroupErrors is nullable: Consumers must explicitly check for null before iterating (e.g., ?.Length or GroupErrors?.Any()).
• GroupHelper.GetChannelIndexes and GetGroupIds: Use exact string/ID matching on nested dictionaries; performance may degrade with large datasets due to nested loops.
• GroupDbRecord.SerialNumber vs GroupName: In GroupDbRecord(IGroup copy, ...), SerialNumber is set to copy.Name, but DisplayName is set separately. Ensure Name and DisplayName are distinct in the IGroup interface.