init

enriched-qwen3-coder-next/Common/DTS.Common.DataModel/Classes/TestTemplate.md

@@ -0,0 +1,142 @@
+---
+source_files:
+  - Common/DTS.Common.DataModel/Classes/TestTemplate/ICachedContainer.cs
+  - Common/DTS.Common.DataModel/Classes/TestTemplate/HardwareInclusionInstruction.cs
+  - Common/DTS.Common.DataModel/Classes/TestTemplate/TSRAIRGoTestSetup.cs
+  - Common/DTS.Common.DataModel/Classes/TestTemplate/DownloadEvent.cs
+  - Common/DTS.Common.DataModel/Classes/TestTemplate/BuildTestSetup.cs
+generated_at: "2026-04-16T03:33:56.095301+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "899d8d4385eb5461"
+---
+
+# Documentation: Test Template Data Model Module
+
+## 1. Purpose
+
+This module defines core data structures and interfaces for configuring and managing test setups in the DataPROWin7 system, specifically for hardware-agnostic test template handling, event download configuration, and build-time test setup generation. It enables programmatic construction of test configurations from XML templates or runtime templates, supports hardware inclusion/exclusion instructions for flexible group-based test composition (e.g., DAS-less groups), and provides caching and singleton access patterns for standardized test setups like `TSRAIR_GO_TEST`. The module serves as the foundational data layer for test configuration, bridging high-level test templates with low-level XML serialization and hardware mapping.
+
+## 2. Public Interface
+
+### `ICachedContainer` (Interface)
+- **Namespace**: `DataPROWin7.DataModel.Classes.TestTemplate`
+- **Purpose**: Provides cached access to hardware, sensor, and calibration data by serial number, and enumeration of all cached hardware.
+- **Methods**:
+  - `DASHardware GetCachedHardware(string serialNumber)`  
+    Retrieves cached DAS hardware data for the given serial number.
+  - `SensorData GetCachedSensor(string serialNumber)`  
+    Retrieves cached sensor data for the given serial number.
+  - `SensorCalibration[] GetCalibrations(string serialNumber)`  
+    Retrieves an array of calibrations associated with the given serial number.
+  - `IISOHardware[] GetAllCachedHardware()`  
+    Returns all hardware currently in the cache.
+
+### `HardwareInclusionInstruction` (Class)
+- **Namespace**: `DataPROWin7.DataModel`
+- **Purpose**: Represents an explicit instruction to include or exclude a specific piece of hardware in a test, overriding group-based inclusion logic.
+- **Properties**:
+  - `string HardwareId { get; }`  
+    The identifier of the hardware to which the instruction applies.
+  - `Actions Action { get; }`  
+    The action to take (`Remove` or `Add`).
+- **Constructors**:
+  - `HardwareInclusionInstruction(string hardwareId, Actions action)`  
+    Creates a new instruction with the specified hardware ID and action.
+  - `HardwareInclusionInstruction(HardwareInclusionInstruction copy)`  
+    Copy constructor.
+
+### `TSRAIRGoTestSetup` (Class)
+- **Namespace**: `DTS.Common.DataModel.Classes.TestTemplate`
+- **Purpose**: Implements a singleton test setup for the `"TSRAIR_GO_TEST"` template, with caching and lazy initialization.
+- **Constants**:
+  - `public const string TEST_NAME = "TSRAIR_GO_TEST"`
+- **Properties**:
+  - `public override string Name { get; }`  
+    Always returns `"TSRAIR_GO_TEST"`; setter is a no-op.
+- **Methods**:
+  - `public static TSRAIRGoTestSetup GetInstance(int userId, bool useCache = true)`  
+    Returns a singleton instance of `TSRAIRGoTestSetup`. If `useCache` is true and an instance exists, returns it; otherwise, loads the template named `"TSRAIR_GO_TEST"` from `TestTemplateList`, or falls back to user-specific defaults if the template is not found. Thread-safe via `lock`.
+
+### `DownloadEvent` (Class)
+- **Namespace**: `DataPROWin7.DataModel`
+- **Purpose**: Represents a downloadable test event with metadata for export and display, implementing `IDownloadEvent` and `INotifyPropertyChanged`.
+- **Properties**:
+  - `int EventNumber { get; set; }`  
+    Event index; setting triggers `EventNumberDisplay` update.
+  - `bool IsEnabled { get; set; }`  
+    Whether the event is active.
+  - `bool IsDefault { get; }`  
+    Read-only; indicates if this is the default event.
+  - `bool IsReadonly { get; set; }`  
+    Indicates if the event is immutable.
+  - `string EventNumberDisplay { get; }`  
+    Display string of the form `"Event XX"` (e.g., `"Event 01"`), derived from `EventNumber`.
+  - `string TestItem { get; set; }`  
+    Stores `"<TestSetup>:<TestId>:("<All or ROI>")` for export (see comment: issue #43387).
+  - `string DTSFile { get; set; }`  
+    Stores the `.DTS` file path for export (see comment: issue #43387).
+  - `TimeSpan EventLength { get; set; }`  
+    Total time available for the download event.
+  - `bool ShouldDisplayLength { get; set; }`  
+    Controls whether `EventLength` is displayed.
+
+### `BuildTestSetup` (Class)
+- **Namespace**: `DataPROWin7.DataModel`
+- **Purpose**: Converts high-level test templates or XML test setup definitions into a structured, serializable representation for UI and export consumption. Implements `IBuildTestSetup` and `INotifyPropertyChanged`.
+- **Constructors**:
+  - `BuildTestSetup(string dasSerialNumber, string testSetupName, ExportFileXMLClass exportFileXML)`  
+    Parses a `ExportFileXMLClass` object to populate properties and groups.
+  - `BuildTestSetup(string dasSerialNumber, string testSetupName, TestTemplate testTemplate)`  
+    Maps properties from a `TestTemplate` instance to string-based properties.
+- **Key Properties** (all `string`-typed for serialization compatibility):
+  - Hardware/Setup: `DASSerialNumber`, `SetupName`, `SetupDescription`
+  - Timing/Triggering: `RecordingMode`, `SamplesPerSecond`, `PreTriggerSeconds`, `PostTriggerSeconds`, `NumberOfEvents`, `WakeUpMotionTimeout`, `ScheduledStartDateTime`, `IntervalBetweenEventStartsMinutes`, `StartWithEvent`, `WakeUpWithMotion`, `TriggerCheckStep`
+  - Diagnostics/Validation: `StrictDiagnostics`, `RequireConfirmationOnErrors`, `WarnOnBatteryFail`, `AllowMissingSensors`, `AllowSensorIdToBlankChannel`, `SuppressMissingSensorsWarning`
+  - Arm/Checklist Steps: `PerformArmChecklist`, `CheckInputVoltage`, `CheckBatteryVoltage`, `CheckSquibResistance`, `CheckSensorIds`, `CheckStartEventLines`, `CheckTiltSensor`, `CheckTemperature`, `RequireAllUnitsPassArmCheckList`, `ExcitationWarmupTimeMS`
+  - Export/Download: `ROIDownload`, `ViewROIDownload`, `DownloadAll`, `ViewDownloadAll`, `Export`, `ExportFolder`, `ExportCh10FilteredEUDesired`, `ExportChryslerDDASDesired`, `ExportCSVADCDesired`, `ExportCSVFilteredDesired`, `ExportCSVMVDesired`, `ExportCSVUnfilteredDesired`, `ExportDiademADCDesired`, `ExportASCDesired`, `ExportHDFADCDesired`, `ExportHDFMVDesired`, `ExportHDFUnfilteredDesired`, `ExportISOFilteredDesired`, `ExportISOUnfilteredDesired`, `ExportRDFADCDesired`, `ExportTDASADCDesired`, `ExportTDMSADCDesired`, `ExportToyotaUnfilteredDesired`, `ExportTSVFilteredDesired`, `ExportTSVUnfilteredDesired`, `ExportXLSXFilteredDesired`, `ExportXLSXUnfilteredDesired`
+  - UI/Display: `ViewRealtime`, `RealtimeCharts`, `ROIStart`, `ROIEnd`, `CommonStatusLine`, `UploadData`, `UploadDataFolder`, `UseLabDetails`, `UseCustomerDetails`, `UseTestEngineerDetails`, `AutoArm`, `Streaming`, `CalibrationBehavior`, `NotAllChannelsRealTime`, `NotAllChannelsViewer`, `QuitTestWithoutWarning`, `MeasureSquibResistances`
+  - Metadata: `LastModified`, `LastModifiedBy`, `UserTags`
+- **Collections**:
+  - `List<GroupXMLClass> Groups { get; set; }`  
+    List of test groups with channels and settings.
+  - `List<LevelTriggerXMLClass> LevelTriggers { get; set; }`  
+    List of level trigger definitions.
+
+## 3. Invariants
+
+- **`TSRAIRGoTestSetup` singleton**: Only one instance exists per application domain (enforced via `lock` and `_setup` field). The `Name` property is immutable and always equals `"TSRAIR_GO_TEST"`.
+- **`DownloadEvent` defaults**: Default constructor initializes `EventNumber = 0`, `IsEnabled = true`, `IsDefault = true`, `IsReadonly = true`. `EventNumberDisplay` is derived from `EventNumber` and formatted as `"Event XX"`.
+- **`BuildTestSetup` property types**: All configuration properties are stored as `string`, even if originally numeric or boolean (e.g., `SamplesPerSecond`, `AutomaticMode`). This is intentional for XML round-tripping.
+- **Export format parsing**: In `DecodeExportFormats`, only the following export formats are decoded to boolean flags (others are commented out and ignored):
+  - `Ch10FilteredEU`, `ChryslerDDAS`, `CSVADC`, `csvfiltered`, `CSVMV`, `csvunfiltered`, `diademadc`, `FIATASC`, `HDFADC`, `HDFMV`, `HDFUnfiltered`, `isofiltered`, `isounfiltered`, `rdfadc`, `tdasadc`, `tdmsadc`, `toyotaunfiltered`, `tsvfiltered`, `tsvunfiltered`, `xlsxfiltered`, `xlsxunfiltered`
+- **`HardwareInclusionInstruction.Action`**: Must be either `Remove` or `Add`; no validation is performed at construction, so callers must ensure valid values.
+
+## 4. Dependencies
+
+### Imports/References (from source):
+- `DTS.Common.Interface.DASFactory.Diagnostics`
+- `DTS.SensorDB`
+- `DTS.Slice.Users.UserSettings`
+- `DTS.Common.Interface.DownloadEvent`
+- `DTS.Common.XMLUtils`
+- `DTS.Common.Enums`
+- `DTS.Common.SharedResource.Strings`
+- `DataPROWin7.DataModel` (internal namespace for `TestTemplate`, `GroupXMLClass`, `ChannelXMLClass`, `LevelTriggerXMLClass`, `ExportFileXMLClass`, `TestSetupDefaults`, `TestTemplateList`, `SupportedExportFormatBitFlags`)
+
+### Inferred Dependencies:
+- **`TestTemplate`**: Required by `TSRAIRGoTestSetup` and `BuildTestSetup` constructors.
+- **`TestTemplateList`**: Used by `TSRAIRGoTestSetup.GetInstance` to retrieve named templates.
+- **`TestSetupDefaults`**: Used by `TSRAIRGoTestSetup.GetInstance` for fallback user settings.
+- **`GroupXMLClass`, `ChannelXMLClass`, `LevelTriggerXMLClass`, `ExportFileXMLClass`**: Referenced in `BuildTestSetup` constructors and XML parsing logic.
+- **`SupportedExportFormatBitFlags`**: Used in `DecodeExportFormats` to decode export format bitmasks.
+
+## 5. Gotchas
+
+- **`TSRAIRGoTestSetup` caching behavior**: The singleton instance is *not* invalidated on user change unless `useCache = false`. Reusing the instance across different users may lead to incorrect settings if `userId` is not consistent.
+- **`BuildTestSetup` string-based properties**: All properties are `string`, even for numeric/boolean values (e.g., `"True"`, `"100"`). Consumers must parse these values appropriately; no runtime type safety is enforced.
+- **Export format decoding is incomplete**: In `DecodeExportFormats`, several formats are commented out (`ExportCh10UnfilteredEUDesired`, `ExportHDFFilteredDesired`, `ExportSomatFilteredDesired`, `ExportSomatUnfilteredDesired`, `ExportToyotaFilteredDesired`). This may cause confusion if export formats are expected to be fully symmetric.
+- **`HardwareInclusionInstruction` immutability**: `HardwareId` and `Action` are read-only (`get;` only), but the class itself is not immutable (e.g., no `readonly` fields). Copy constructor exists but is not enforced.
+- **`DownloadEvent.TestItem` and `DTSFile`**: These properties are documented as being for export (issue #43387), but there is no validation or enforcement of their format or usage. Misuse could break export logic.
+- **`BuildTestSetup.ParseSettings`**: Uses hardcoded string prefixes (e.g., `"0="`, `"1="`) to parse settings. If the XML format changes or prefixes are reordered, parsing will silently fail or misassign values.
+- **Thread safety**: `TSRAIRGoTestSetup.GetInstance` is thread-safe via `lock`, but no other classes in this module declare thread-safety guarantees. Concurrent access to shared mutable state (e.g., `DownloadEvent` properties) is not protected.