init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/TestSetups/TestSetupsList.md

@@ -0,0 +1,166 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/TestSetups/TestSetupsList/ITestSetupsListView.cs
+  - Common/DTS.Common/Interface/TestSetups/TestSetupsList/ITestSetupsListViewModel.cs
+  - Common/DTS.Common/Interface/TestSetups/TestSetupsList/ITestSetup.cs
+  - Common/DTS.Common/Interface/TestSetups/TestSetupsList/ITestSetupRecord.cs
+  - Common/DTS.Common/Interface/TestSetups/TestSetupsList/ITestTemplate.cs
+generated_at: "2026-04-16T03:12:20.673126+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "f902db33527ae56d"
+---
+
+# TestSetupsList
+
+### **Purpose**  
+This module defines the core interfaces for managing test setups within the DTS (Data Acquisition and Test System) framework. It establishes the contract between the UI layer (`ITestSetupsListView`) and the business logic layer (`ITestSetupsListViewModel`), while also modeling the data structures (`ITestSetup`, `ITestSetupRecord`, `ITestTemplate`) that represent individual test configurations—including hardware, groups, sensors, channels, triggers, and execution behavior. The module enables listing, filtering, sorting, and manipulating test setups, serving as the foundational abstraction for test setup creation, editing, and validation across the application.
+
+---
+
+### **Public Interface**
+
+#### **Interfaces**
+All interfaces reside in the namespace `DTS.Common.Interface.TestSetups.TestSetupsList`.
+
+##### `ITestSetupsListView`
+- **Inherits**: `IBaseView`
+- **Purpose**: UI view contract for the test setups list screen. No additional members beyond base view functionality—implementation is expected to bind to `ITestSetupsListViewModel`.
+
+##### `ITestSetupsListViewModel`
+- **Inherits**: `IBaseViewModel`, `IFilterableListView`
+- **Properties**:
+  - `ITestSetupsListView View { get; set; }` — Back-reference to the bound view.
+  - `ITestSetup[] TestSetups { get; set; }` — Current list of test setups displayed (e.g., filtered/sorted).
+- **Methods**:
+  - `void SetTestSetups(ITestSetup[] allTestSetups)` — Replaces the full list of test setups (e.g., after loading from DB).
+  - `void Sort(object sortBy, bool bColumnClick)` — Sorts the current `TestSetups` list based on `sortBy` (typically a column key), with `bColumnClick` indicating UI-initiated sorting.
+  - `void Unset()` — Clears state (e.g., resets view model when navigating away).
+  - `void Filter(string currentFilter)` — Filters `TestSetups` based on `currentFilter` (e.g., text search).
+  - `void MouseDoubleClick(int index)` — Handles double-click on item at `index` (e.g., opens edit dialog).
+
+##### `ITestSetupRecord`
+- **Inherits**: None (base record interface)
+- **Purpose**: Represents a *persistent* test setup record (database entity), containing metadata and configuration flags.
+- **Key Properties** (selected highlights):
+  - `int Id`, `string Name`, `string Description`
+  - `bool AutomaticProgression`, `int AutomaticProgressionDelayMS`
+  - `RecordingModes RecordingMode`, `double SamplesPerSecondAggregate`, `double PreTriggerSeconds`, `double PostTriggerSeconds`, `int NumberOfEvents`
+  - `bool StrictDiagnostics`, `bool RequireUserConfirmationOnErrors`
+  - `bool DoROIDownload`, `bool ViewROIDownload`, `bool DownloadAll`, `bool ViewRealtime`, `short DefaultNumberRealtimeGraphs`
+  - `bool CheckoutMode`, `bool LocalOnly`, `bool Dirty`, `bool IsComplete`, `string ErrorMessage`
+  - `DateTime LastModified`, `string LastModifiedBy`
+  - `bool CommonStatusLine`, `bool UploadData`, `string UploadFolder`, `bool UploadExportsOnly`
+  - `bool TriggerCheckStep`, `bool PostTestDiagnosticsLevel`
+  - `bool LowgLevelTriggerOn`, `bool HighgLevelTriggerOn`, `bool AngularRateLevelTriggerOn`, etc. (and per-axis variants)
+  - `bool MeasureSquibResistancesStep`, `string TestSetupUniqueId`, `bool DoAutoArm`, `bool DoEnableRepeat`
+  - `ClockSyncProfile ClockSyncProfileMaster`, `ClockSyncProfile ClockSyncProfileSlave`
+  - `List<IExtraProperty> ExtraProperties`
+  - `bool AlignUDPToPPS`
+- **Methods**:
+  - `void Copy(ITestSetupRecord copy)` — Deep copy from another record.
+  - `void InitializeFromDefaults(CalibrationBehaviors, RecordingModes, double preTriggerSeconds, double postTriggerSeconds, int numEvents)` — Initialize with default values.
+
+##### `ITestSetup`
+- **Inherits**: `ITestSetupRecord`
+- **Purpose**: Represents a *runtime* test setup instance, extending `ITestSetupRecord` with hardware/group/sensor management and runtime state.
+- **Properties**:
+  - `Dictionary<IGroup, IGroupChannel[]> ChannelsForGroup { get; set; }`
+  - `Dictionary<string, bool> DASClockMasterList { get; set; }`
+  - `Dictionary<string, double> DASSampleRateList { get; set; }`
+  - `Dictionary<string, float> DASAAFRateList { get; set; }`
+  - `Dictionary<string, List<string>> EncapsulatedDASList { get; set; }`
+  - `Visibility TooltipVisibility { get; }`, `string TooltipMessage { get; }`, `string CompletionErrorMessage { get; }`
+  - `ObservableCollection<IGroup> Groups { get; set; }`
+  - `int[] AddedHardware { get; set; }`, `int[] RemovedHardware { get; set; }`
+- **Methods**:
+  - `void AddGroup(IGroup group, IDictionary<int, ISensorData> sensorLookup, IDictionary<long, IGroupChannel> channelLookup)` — Adds a group with lookups.
+  - `double GetSampleRate(string dasSerialNumber, double defaultValue)` — Gets sample rate for DAS, falling back to `defaultValue`.
+  - `bool Filter(string term)` — Filters internal groups/channels by `term`.
+  - `int[] GetAllIncludedHardware()` — Returns all hardware IDs included (via groups + explicit add/remove overrides).
+  - `void AddHardware(int dasId, string dasSerialNumber, IDASHardware[] allHardware, IDictionary<int, IDASHardware> lookup)`  
+    `void AddHardware(int dasId, IDictionary<int, IDASHardware> lookup)`  
+    `void RemoveHardware(int dasId, IDASHardware[] allHardware, IDictionary<int, IDASHardware> lookup)` — Explicit hardware management.
+  - `void SaveGroups()`, `void SaveHardware()` — Persist group/hardware state.
+  - `void RemoveGroup(IGroup group)`, `void MoveGroupUp(IGroup group)`, `void MoveGroupDown(IGroup group)`, `void MoveGroupToDisplayOrder(IGroup group, int displayOrder)` — Group ordering.
+  - `List<IGroupChannel> GetChannels()` — Returns all channels in test.
+  - `void SetTestSetupChannelOrder()` — Persists channel ordering.
+
+##### `ITestTemplate`
+- **Inherits**: `ITestSetup`
+- **Purpose**: Represents the *heavy* runtime implementation of `ITestSetup`, with additional methods for test execution, serialization, and dynamic group/hardware handling.
+- **Properties**:
+  - `bool LowgLevelTriggersMixed`, `double LowgLinearLevelTriggerAggregate`, etc. (aggregated trigger state flags)
+  - `bool? DestructiveTest { get; set; }` — Runtime flag indicating destructive test (not serialized).
+  - `bool QuickSensorCheck`, `bool ExpressTestSetup`, `bool PreserveTestId`
+  - `bool IsLoaded { get; }`, `bool ArmCheckListStep`, `bool CheckListBatteryVoltageCheck`, etc. (checklist steps)
+  - `Dictionary<string, double> FilterLookup { get; set; }`
+  - `int ExcitationWarmupTimeMS`, `int GraphCount`, `string SetupFile`, `string TestId`, `string TestDirectory`, `string DownloadFolder`, `string ExportFolder`, `DateTime TestTime`, `int ChannelCount`, `int IncludedChannelCount`
+  - `bool GroupsStepValid`, `List<string> CheckedDASList`
+- **Methods**:
+  - `void CreateCopy()` — Removes DB IDs to create a new test setup.
+  - `void ClearHardware()` — Clears all hardware.
+  - `void Rename(bool bAddedGroups)` — Renames test setup and regenerates groups (to avoid shared group references).
+  - `void SetGroupsListOrder()` — Sets display orders based on group list order.
+  - `void ReplaceLevelTriggerChannel(...)` — Overloads for updating level trigger channel mappings (e.g., after group rename).
+  - `void RefreshSensorsFromDb()` — Reloads sensors from DB while preserving custom overrides.
+  - `void SetDisabled(string groupName, string channelName, bool disabled)` — Disables a channel (excludes from test run).
+  - `void RemoveSensor(string sensorserialnumber, string testobjectserial, string channelname)` — Removes a sensor assignment.
+  - `void WriteXML(ref XmlWriter writer)` — Serializes test setup to XML.
+  - `void Load(bool fromDB = false)`, `void LoadFromDb()`, `void UnLoad()`, `void ReloadGroups(bool bMemoryOnly)` — Lifecycle management.
+  - `void CalculateIsComplete(bool bSetInDb = true)` — Computes `IsComplete` and `ErrorMessage`; may load from DB if needed.
+  - `void MarkIsCompleteUnchecked(bool skipMemoryCheck = false)` — Sets `Dirty = true` and persists to DB.
+  - `double GetSampleRateForHardware(string h)`, `float GetAAFForHardware(IDASCommunication das)`, `float GetAAFForHardware(IDASCommunication das, int sps)`, `float GetRealtimeAAFForHardware(IDASCommunication idas, double samplerate)` — Hardware-specific rate/AAF calculations.
+  - `void SetHardwareOverride(string hid, bool bAdd)` — Explicitly adds/removes hardware.
+  - `void UpdateDynamicGroupFromStaticGroup(IGroup _updateGroup, IGroup staticGroup)` — Converts dynamic group to static snapshot.
+  - `void Rename(string newName)` — Renames test setup (updates metadata).
+
+---
+
+### **Invariants**
+- `ITestSetupRecord.IsComplete` is **dependent** on `Dirty`: if `Dirty == true`, `IsComplete` is not guaranteed to be accurate and must be recalculated via `CalculateIsComplete`.
+- `ITestSetupRecord.ErrorMessage` is cached and may be stale if `Dirty == true`; it is updated only during completion calculation.
+- `ITestSetup.AddedHardware` and `RemovedHardware` override hardware inclusion/exclusion derived from groups.
+- `ITestSetupRecord.CheckoutMode` implies special behavior (e.g., relaxed diagnostics, no sensor data collection), but enforcement is implementation-dependent.
+- `ITestTemplate.DestructiveTest` is **not serialized**—it is a runtime-only flag.
+- `ITestSetupRecord.LastModified` and `LastModifiedBy` are updated only when persisted to DB; in-memory changes do not auto-update them.
+- `ITestSetupRecord.LocalOnly` is deprecated; its usage is legacy and should be ignored in new development.
+- `ITestSetupRecord.Dirty` is **not persisted** by property setters—explicit calls to `MarkIsCompleteUnchecked` or `CalculateIsComplete` are required to persist changes.
+
+---
+
+### **Dependencies**
+#### **Imports/References**
+- `DTS.Common.Base` — Provides `IBaseView`, `IBaseViewModel`, `IFilterableListView`.
+- `DTS.Common.Interface.Pagination` — Provides `IFilterableListView`.
+- `DTS.Common.Interface.Channels` — `IGroupChannel`, `IDASHardware`.
+- `DTS.Common.Interface.DataRecorders` — `IDASHardware`.
+- `DTS.Common.Interface.Groups.GroupList` — `IGroup`.
+- `DTS.Common.Interface.Sensors` — `ISensorData`, `ISensorCalibration`.
+- `DTS.Common.Enums` — `RecordingModes`, `CalibrationBehaviors`, `SupportedExportFormatBitFlags`, `TimeUnitTypeEnum`, `WakeUpTriggers`, `ClockSyncProfile`.
+- `DTS.Common.Interface.ISO.ExtraProperties` — `IExtraProperty`.
+- `DTS.Common.Interface.RegionOfInterest` — `IRegionOfInterest`.
+- `System`, `System.Collections.Generic`, `System.Collections.ObjectModel`, `System.ComponentModel`, `System.Windows`, `System.Xml`.
+
+#### **Depended Upon By**
+- UI layers (e.g., WPF views implementing `ITestSetupsListView`).
+- Persistence layers (e.g., database access code mapping `ITestSetupRecord` to DB tables).
+- Test execution engine (consumes `ITestSetup`/`ITestTemplate` for runtime configuration).
+- Group management, sensor management, and channel configuration modules.
+
+---
+
+### **Gotchas**
+- **`ITestSetup.AddGroup` overloads**: Two overloads exist (`IDictionary<long, IGroupChannel>` vs `IDictionary<int, IDASHardware>`). Ensure correct overload is used depending on context (channel lookup key type).
+- **`ITestSetupRecord.IsComplete` vs `ITestSetup.CalculateIsComplete`**: `IsComplete` on `ITestSetupRecord` is a *database field*; `ITestSetup.CalculateIsComplete` computes it *in-memory* and may load from DB if needed. Do not assume `IsComplete` is up-to-date without calling `CalculateIsComplete`.
+- **`ITestTemplate.DestructiveTest` is not serialized**: Setting this flag has no effect on saved test setups—it is only used at runtime (e.g., to set first-use dates).
+- **Hardware override methods**: `AddHardware`/`RemoveHardware` on `ITestSetup` bypass group-based hardware inclusion. `GetAllIncludedHardware()` accounts for these overrides.
+- **Group renaming**: `ITestTemplate.Rename(bool bAddedGroups)` regenerates groups to avoid shared references—do not assume group IDs remain stable after renaming.
+- **Level trigger channel mapping**: Multiple `ReplaceLevelTriggerChannel(...)` overloads exist for handling group/ID renames. Ensure correct overload is used to avoid stale references.
+- **`ITestSetupRecord.Settings`**: Serialized string stored in DB; requires `GetSettings()`/`LoadSettings(string)` to manage. Not auto-synchronized.
+- **`ITestSetupRecord.TagsBlobBytes`**: Binary blob for tags—no schema defined; interpretation is implementation-specific.
+- **`ITestTemplate.IsLoaded`**: Indicates whether runtime data (groups, channels, etc.) is loaded. `Load()`/`UnLoad()` must be called explicitly—no automatic lazy loading is implied.
+- **`ITestSetupRecord.LastModified`**: Not updated on property changes; must be set manually before persistence.
+- **`ITestSetupRecord.CheckoutMode`**: Has multiple internal meanings (e.g., strict diagnostics, sensor data collection). Behavior is not fully documented—verify with implementation.
+- **`ITestSetupRecord.LocalOnly`**: Deprecated—ignore in new features.
+- **`ITestSetupRecord.Dirty`**: Not persisted by property setters—must be set via `MarkIsCompleteUnchecked()` or `CalculateIsComplete()` to persist to DB.