init

docs/ai/Common/DTS.CommonCore/Classes/Groups.md

@@ -0,0 +1,170 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportError.cs
+  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportGroup.cs
+  - Common/DTS.CommonCore/Classes/Groups/GroupHardwareDbRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/TestSetupGroupRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/GroupDbRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/GroupGRPImportChannel.cs
+  - Common/DTS.CommonCore/Classes/Groups/ChannelDbRecord.cs
+  - Common/DTS.CommonCore/Classes/Groups/GroupHelper.cs
+generated_at: "2026-04-17T15:32:21.714066+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "b21188904e1c0fcd"
+---
+
+# Documentation: DTS.Common.Classes.Groups
+
+## 1. Purpose
+
+This module provides data structures for managing groups and channels within the DTS (Data Test System) application. It handles three primary concerns: (1) importing `.GRP` files containing channel configurations with associated validation error tracking, (2) representing database records for groups, channels, and hardware associations with `INotifyPropertyChanged` support for UI binding, and (3) maintaining static lookup caches via `GroupHelper` for cross-referencing groups, channels, DAS devices, and test setups. The module serves as the data layer between raw file imports, persistent storage, and the application's business logic.
+
+---
+
+## 2. Public Interface
+
+### GroupGRPImportError
+Encapsulates errors encountered during `.GRP` file import.
+
+```csharp
+public class GroupGRPImportError
+{
+    public enum Errors
+    {
+        FileEmpty, InvalidISOCodeInput, InvalidFullScaleInput, InvalidSensorInput,
+        InvalidInvertInput, SensorNotFound, InvalidInputMode, InvalidDefaultValue,
+        InvalidActiveValue, InvalidFireMode, InvalidDelay, InvalidLimitDuration,
+        InvalidDuration, InvalidCurrent
+    }
+    
+    public Errors ErrorCode { get; set; }
+    public string File { get; set; }
+    public int Line { get; set; }
+    public string ExtraInfo { get; set; }
+    public override string ToString()  // Returns ExtraInfo
+}
+```
+
+### GroupGRPImportGroup
+Represents an entire group parsed from a `.GRP` file.
+
+```csharp
+public class GroupGRPImportGroup : BasePropertyChanged
+{
+    public bool Included { get; set; } = true;
+    public bool Overwrite { get; set; } = true;
+    public string GroupName { get; set; }
+    public string GroupTags { get; set; }
+    public string ImportingUserTags { get; set; }
+    public string SourceFile { get; set; }
+    public GroupGRPImportChannel[] Channels { get; set; } = { };
+    public GroupGRPImportError[] GroupErrors { get; set; } = null;
+    public bool GroupNameHasError { get; set; }  // Notifies property change
+}
+```
+
+### GroupGRPImportChannel
+Represents a single channel/row from a TDC GRP file.
+
+```csharp
+public class GroupGRPImportChannel : BasePropertyChanged
+{
+    // Field position constants for parsing
+    public const uint SerialNumberField = 0;
+    public const uint DisplayNameField = 1;
+    public const uint ISOCodeField = 2;
+    public const uint InvertField = 3;
+    public const uint CapacityField = 4;
+    public const uint InputModeField = 5;
+    public const uint DefaultValueField = 6;
+    public const uint ActiveValueField = 7;
+    public const uint FireModeField = 8;
+    public const uint DelayField = 9;
+    public const uint LimitDurationField = 10;
+    public const uint DurationField = 11;
+    public const uint CurrentField = 12;
+
+    public enum InputModes { na, TLH, THL, CCNO, CCNC }
+    public enum FireModes { na, CD, CC }
+
+    // Default constants
+    public const InputModes DefaultInputMode = InputModes.CCNO;
+    public const double DefaultDefaultValue = 0.0;
+    public const double DefaultActiveValue = 1.0;
+    public const FireModes DefaultFireMode = FireModes.CD;
+    public const double DefaultDelay = 0.00;
+    public const bool DefaultLimitDuration = true;
+    public const double DefaultDuration = 10.0;
+    public const double DefaultCurrent = 1.5;
+
+    // Properties
+    public string SensorSerialNumber { get; set; }
+    public string DisplayName { get; set; }
+    public string ISOCode { get; set; }
+    public bool Invert { get; set; }
+    public double FullScale { get; set; }
+    public InputModes? InputMode { get; set; } = null;
+    public double? DefaultValue { get; set; } = null;
+    public double? ActiveValue { get; set; } = null;
+    public FireModes? FireMode { get; set; } = null;
+    public double? Delay { get; set; } = null;
+    public bool? LimitDuration { get; set; } = null;
+    public double? Duration { get; set; } = null;
+    public double? Current { get; set; } = null;
+    public GroupGRPImportError Error { get; set; } = null;
+    public GroupGRPImportGroup ParentGroup { get; set; }
+    public string GroupName { get; }  // Returns ParentGroup.GroupName or "---"
+
+    public void GroupNameInvalidate();  // Raises PropertyChanged for GroupName
+}
+```
+
+### GroupDbRecord
+Database record for a group, implements `IGroupDbRecord`.
+
+```csharp
+public class GroupDbRecord : BasePropertyChanged, IGroupDbRecord
+{
+    [Key] public int Id { get; set; }
+    public string SerialNumber { get; set; }
+    public string Picture { get; set; }
+    public string DisplayName { get; set; }
+    public string Description { get; set; }
+    public bool Embedded { get; set; }
+    public DateTime LastModified { get; set; }
+    public string LastModifiedBy { get; set; }
+    public int? StaticGroupId { get; set; }
+    public string ExtraProperties { get; set; }
+
+    public GroupDbRecord();
+    public GroupDbRecord(IGroupDbRecord copy);
+    public GroupDbRecord(IGroup copy, List<KeyValuePair<string,string>> extraProperties);
+    public GroupDbRecord(IDataReader reader);
+}
+```
+
+### ChannelDbRecord
+Database record for a channel, implements `IChannelDbRecord`.
+
+```csharp
+public class ChannelDbRecord : BasePropertyChanged, IChannelDbRecord
+{
+    [Key] public long Id { get; set; }
+    public int GroupId { get; set; }
+    public string IsoCode { get; set; }
+    public string IsoChannelName { get; set; }
+    public string UserCode { get; set; }
+    public string UserChannelName { get; set; }
+    public int DASId { get; set; }
+    public int DASChannelIndex { get; set; }
+    public int GroupChannelOrder { get; set; }
+    public int TestSetupOrder { get; set; }
+    public int SensorId { get; set; }
+    public bool IsDisabled { get; set; }  // Redirects to Disabled, raises PropertyChanged for "IsDisabled"
+    public bool Disabled { get; set; }
+    public DateTime LastModified { get; set; }
+    public string LastModifiedBy { get; set; }
+
+    public ChannelDbRecord();
+    public ChannelDbRecord(IChannelDbRecord copy