init

enriched-qwen3-coder-next/DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject.md

@@ -0,0 +1,263 @@
+---
+source_files:
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TemplateChannelUI.cs
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TestObjectTemplateCollection.cs
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TestObjectList.cs
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TestTestObject.cs
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TestObjectTemplate.cs
+  - DataPRO/Modules/DatabaseImporter/DatabaseImport/Classes/TestObject/TestObject.cs
+generated_at: "2026-04-16T04:33:08.085586+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "d8ddaddf5f4cb968"
+---
+
+# TestObject
+
+**Documentation Page: Test Object & Template Management Module**
+
+---
+
+### 1. **Purpose**
+
+This module provides in-memory wrappers and management abstractions for test object and template data originating from the `ISO.TestObject` and `ISO.TestObjectTemplate` types in the underlying `ISO` namespace. It serves as the data-access and UI-binding layer for test object configurations, templates, and associated channel/sensor metadata within the `DatabaseImporter` module. Its primary role is to decouple UI and business logic from raw database structures (`ISO13499FileDb`) while supporting both ISO-compliant and non-ISO (custom) test object types, and enabling template reuse, inheritance, and zone-based channel organization.
+
+---
+
+### 2. **Public Interface**
+
+#### `TemplateChannelUI`
+- **`TemplateChannelUI(TestObjectTemplateChannel channel)`**  
+  Constructor wrapping a `TestObjectTemplateChannel`. No public properties or methods exposed beyond the internal `_channel` field.
+
+#### `TestObjectTemplateCollection`
+- **`static TestObjectTemplateCollection TemplateCollection { get; }`**  
+  Singleton accessor for the global collection of test object templates.
+- **`TestObjectTemplate GetTemplate(string templateId)`**  
+  Retrieves a `TestObjectTemplate` by ID from the database (`IsoDb`) and wraps it in a `TestObjectTemplate` instance. Returns `null` if not found.
+- **`TestObjectTemplate SysBuiltTestObjectTemplate { get; }`**  
+  Returns the system-built template (currently uninitialized in source; `_sysBuiltTestObjectTemplate` is `null`).
+- **`void ReloadAll(bool loadSubComponents)`**  
+  Stubbed out (all logic commented out). Intended to refresh templates and subcomponents.
+- **`static void DeleteAll()`**  
+  Deletes all templates in the database via `ISO.TestObjectTemplate.DeleteAllTemplates()`, then resets the singleton collection.
+
+#### `TestObjectList`
+- **`static TestObjectList TestObjectsList { get; }`**  
+  Singleton accessor for the main list of test objects (non-system-built).
+- **`static TestObjectList AddedGroupsList { get; }`**  
+  Singleton accessor for a separate list used for user-added groups (system-built).
+- **`void ReloadAll(bool bLoadSubComponents)`**  
+  Stubbed out (empty body). Intended to reload all test objects and subcomponents.
+- **`TestObject GetTestObject(string serialNumber, bool bSysBuilt)`**  
+  Retrieves a test object by serial number and `bSysBuilt` flag. Returns `null` if not found.
+- **`TestObject GetTestObject(string serialNumber)`**  
+  Convenience overload: tries non-system-built first, then system-built.
+- **`TestObject GetAddedGroup(string serialNumber)`**  
+  Alias for `GetTestObject(serialNumber, true)`.
+- **`void DeleteAll()`**  
+  Deletes all test objects in the database via `ISO.TestObject.DeleteAllTestObjects()`.
+
+#### `TestTestObject`
+- **`TestTestObject(TestObject obj)`**  
+  Constructor wrapping a `TestObject`.
+- **`MMEPositions Position { get; set; }`**  
+  Gets/sets the group position. Setting to `UserSetKey` (`"@"`) hides the combo box and shows the position button; otherwise, vice versa. Also propagates position to all required sensors.
+- **`string ChannelDefaultsKey { get; }`**  
+  Constant `"#"` representing the default channel position.
+- **`string UserSetKey { get; }`**  
+  Constant `"@"` representing a user-defined position.
+- **`Visibility GroupPositionComboBoxVisible { get; set; }`**  
+  Controls visibility of the position combo box. Collapsed if `ISO13499` support is disabled (`NO_ISO`).
+- **`Visibility GroupPositionButtonVisible { get; set; }`**  
+  Controls visibility of the position button. Collapsed if `ISO13499` support is disabled.
+- **`MMETestObjects TestObject { get; set; }`**  
+  Gets/sets the test object for the group. Setting it propagates the change to all required sensors.
+- **`int ChannelTypesIndex { get; set; }`**  
+  Index into a list of channel types (used for UI binding).
+- **`int ExcitationWarmupTimeMS { get; set; }`**  
+  Excitation warm-up time in milliseconds.
+- **`double TargetSampleRate { get; set; }`**  
+  Target sample rate.
+- **`double PreTriggerSeconds { get; set; }`**  
+  Pre-trigger duration in seconds.
+- **`double PostTriggerSeconds { get; set; }`**  
+  Post-trigger duration in seconds.
+- **`MMEPositions[] AvailablePositions { get; }`**  
+  Returns available positions from `IsoDb`.
+- **`MMEPositions[] AvailableGroupPositions { get; }`**  
+  Returns combined list: `ChannelDefaultsKey` position first, then `AvailablePositions`.
+- **`void SetTestObject(string s)`**  
+  Sets `_testObject` and raises `TestObject` property change.
+- **`void SetPosition(string s)`**  
+  Sets `_position` and raises `Position` change; updates UI visibility flags.
+
+#### `TestObjectTemplate`
+- **`TestObjectTemplate()`**  
+  Default constructor. Initializes `TestObject` based on `SerializedSettings.ISOSupportLevel`. For `NO_ISO`, creates a non-ISO test object and sets channel type to `Constants.NON_ISO_TESTOBJECT_CHANNEL_TYPE`.
+- **`TestObjectTemplate(ISO.TestObjectTemplate template, ref ISO13499FileDb db)`**  
+  Wraps an `ISO.TestObjectTemplate` instance.
+- **`TestObjectTemplate(TestObjectTemplate copy, ref ISO13499FileDb db)`**  
+  Copy constructor.
+- **`string TemplateName { get; set; }`**  
+  Template name.
+- **`string TemplateDescription { get; set; }`**  
+  Template description.
+- **`string TemplateParent { get; set; }`**  
+  Parent template name (for inheritance).
+- **`bool SysBuilt { get; set; }`**  
+  Whether the template is system-built.
+- **`bool Embedded { get; set; }`**  
+  Whether the template is embedded.
+- **`string OriginalTemplateName { get; set; }`**  
+  Original template name (preserved for tracking).
+- **`MMETestObjects TestObject { get; set; }`**  
+  Test object associated with the template.
+- **`string TestObjectType { get; set; }`**  
+  Test object type (e.g., channel type).
+- **`int TestObjectTypeIndex { get; set; }`**  
+  Index into `AvailableTestObjectTypes`.
+- **`string[] AvailableTestObjectTypes { get; set; }`**  
+  List of test object types compatible with current `TestObject`.
+- **`TestObjectTemplateChannel[] RequiredChannels { get; }`**  
+  List of required channels for the template.
+- **`TestObjectTemplateChannel[] TemplateAllChannels { get; set; }`**  
+  All channels (required + optional), sorted by `DisplayOrder`.
+- **`TemplateChannelUI[] TemplateAllUIChannels { get; set; }`**  
+  UI wrapper list for `TemplateAllChannels`.
+- **`Zone[] TemplateZones { get; set; }`**  
+  List of zones defined in the template.
+- **`int CurrentZoneIndex { get; set; }`**  
+  Index of the currently selected zone. Updates `CurrentZone`.
+- **`Zone CurrentZone { get; set; }`**  
+  Currently selected zone. Controls `AreZoneControlsEnabled`.
+- **`bool AreZoneControlsEnabled { get; }`**  
+  `true` if `CurrentZone` is non-null.
+- **`DateTime LastModified { get; set; }`**  
+  Last modification timestamp.
+- **`string LastModifiedBy { get; set; }`**  
+  User who last modified the template.
+- **`static MMETestObjects GetNonISOTestObject()`**  
+  Retrieves or creates a non-ISO test object (name: `Constants.NON_ISO_TESTOBJECT_NAME`). Tries letters A–Z, then digits 0–9.
+- **`ISO.TestObjectTemplate ToISOTestObjectTemplate()`**  
+  Converts the wrapper to an `ISO.TestObjectTemplate` instance for persistence.
+
+#### `TestObject`
+- **`TestObject()`**  
+  Default constructor. Initializes empty `_isoTestObject` and `Template`.
+- **`TestObject(ISO.TestObject to, bool sysBuilt)`**  
+  Wraps an `ISO.TestObject`. Initializes `Template` and hardware.
+- **`TestObject(TestObject copy)`**  
+  Copy constructor.
+- **`string SerialNumber { get; set; }`**  
+  Unique serial number.
+- **`string SerialNumberConverted { get; set; }`**  
+  Human-readable serial number (e.g., stripped prefix for system-built).
+- **`string DisplaySerialNumber { get; set; }`**  
+  Serial number used for display. Setting it updates `SerialNumber`, `OriginalSerialNumber`, and template name.
+- **`string TestSetupName { get; set; }`**  
+  Name prefix for user-added groups.
+- **`string TestObjectType { get; set; }`**  
+  Type of the test object (from template).
+- **`string ParentObject { get; set; }`**  
+  Parent test object (for hierarchy).
+- **`bool SysBuilt { get; set; }`**  
+  Whether the test object is system-built.
+- **`TestObjectTemplate Template { get; set; }`**  
+  Template associated with the test object.
+- **`void SetTemplateDontResetISOObject(TestObjectTemplate value)`**  
+  Sets template without resetting underlying `ISO.TestObject.Template`.
+- **`string[] ZoneNames { get; set; }`**  
+  Names of zones in the current template.
+- **`string TemplateType { get; }`**  
+  `Template.TestObjectType`, or `""` if no template.
+- **`DASHardware[] Hardware { get; }`**  
+  List of attached hardware devices, sorted.
+- **`void SetHardwareFromISO()`**  
+  Refreshes `_hardware` from `ISO.TestObject.HardwareIds`.
+- **`void SetHardware(DASHardware[] hardware)`**  
+  Sets hardware list in memory and updates `ISO.TestObject.HardwareIds`.
+- **`void AddHardware(DASHardware hardware)`**  
+  Adds hardware, handling dummy hardware naming collisions.
+- **`bool ContainsHardware(DASHardware h)`**  
+  Checks if hardware is attached.
+- **`SensorData GetSensor(string channelId, string serialNumber, string alternateChannelId = null)`**  
+  Retrieves sensor settings for a given channel and serial number. Applies ISO channel defaults and overrides from `ISO.TestObject.SensorSettings`.
+- **`void SetSensor(string channelName, SensorData sensor)`**  
+  Persists sensor settings to the underlying `ISO.TestObject`.
+- **`ISO.TestObject GetISOTestObject()`**  
+  Returns the underlying `ISO.TestObject` instance.
+- **`void RefreshHardware()`**  
+  Alias for `SetHardwareFromISO()`.
+- **`string SerialNumberOrOriginalSerialNumber { get; }`**  
+  Returns `OriginalSerialNumber` if embedded, else `SerialNumberConverted` or `SerialNumber`.
+- **`SerializedSettings.ISOSupportLevels GetObjectISOLevel()`**  
+  Returns `NO_ISO` if template type contains `NON_ISO_TESTOBJECT_CHANNEL_TYPE` or `NONISOCHANNELTYPE`, else `ISO_ONLY`.
+
+---
+
+### 3. **Invariants**
+
+- **Singleton consistency**:  
+  `TestObjectTemplateCollection.TemplateCollection` and `TestObjectList.TestObjectsList`/`AddedGroupsList` are lazily initialized singletons. Thread-safety is ensured via `volatile` and `lock(MyLock)` (in `TestObjectList`).
+- **Template ↔ ISO mapping**:  
+  Every `TestObjectTemplate` wraps exactly one `ISO.TestObjectTemplate`, and vice versa. The `ToISOTestObjectTemplate()` method must produce a valid `ISO.TestObjectTemplate` with all fields populated.
+- **Sensor settings precedence**:  
+  `TestObject.GetSensor()` applies ISO channel defaults *first*, then overlays `SensorSettings` from `ISO.TestObject`. If `FilterClassIso` is `"?"`, it is normalized to `"P"`.
+- **Channel ordering**:  
+  `TemplateAllChannels` is sorted by `DisplayOrder` (via `CompareChannels`).
+- **Non-ISO test object uniqueness**:  
+  `GetNonISOTestObject()` ensures a single non-ISO test object exists, using letters A–Z first, then digits 0–9 if needed.
+- **Template type consistency**:  
+  `TestObject.TemplateType` is derived from `Template.TestObjectType`. If `Template` is `null`, it returns `""`.
+
+---
+
+### 4. **Dependencies**
+
+#### **Internal Dependencies**
+- `ISO.TestObject`, `ISO.TestObjectTemplate`, `ISO13499FileDb` (from `ISO` namespace).
+- `App.IsoDb` (accessed via `Application.Current as App`).
+- `DASHardware`, `DASHardwareList`, `SensorData`, `SensorsCollection.SensorsList`.
+- `MMEPositions`, `MMETestObjects`, `MMEPossibleChannels`.
+- `SerializedSettings`, `Constants` (e.g., `NON_ISO_TESTOBJECT_NAME`, `NON_ISO_TESTOBJECT_CHANNEL_TYPE`).
+- `Zone`, `TemplateZone`, `TestObjectTemplateChannel`.
+- `DbTimeStampBase` (base class for `TestObject`).
+- `Tags` enum (used for property change notifications).
+
+#### **External Dependencies**
+- `System.Windows` (for `Visibility`, `Application`, `Guid.NewGuid()`).
+- `System.Globalization` (for `CultureInfo.InvariantCulture` parsing).
+- `System.Linq` (for LINQ queries in `GetNonISOTestObject()` and `TestObjectTemplate` initialization).
+
+#### **Dependents**
+- UI layers (e.g., WPF views binding to `TemplateChannelUI`, `TestObject`, `TestTestObject`).
+- Import/export logic (e.g., TDM imports calling `DeleteAll()` on `TestObjectList` or `TestObjectTemplateCollection`).
+- Template management UI (e.g., zone editing, channel assignment).
+
+---
+
+### 5. **Gotchas**
+
+- **`SysBuiltTestObjectTemplate` is uninitialized**:  
+  `_sysBuiltTestObjectTemplate` is declared but never assigned. `SysBuiltTestObjectTemplate` will always return `null`.
+- **`ReloadAll` stubbed out**:  
+  Both `TestObjectTemplateCollection.ReloadAll()` and `TestObjectList.ReloadAll()` have no implementation (all logic commented out). This may cause stale data if callers assume reload occurs.
+- **`TemplateAllChannels` setter triggers side effects**:  
+  Setting `TemplateAllChannels` in `TestObjectTemplate` instantiates `TemplateAllUIChannels` and updates `_channels` and `_availableTestObjectTypes`. This may cause unexpected behavior if called multiple times.
+- **`TestObject.GetSensor()` uses ambiguous channel lookup**:  
+  The method tries `channelId` first, then `alternateChannelId` (often `channelId` again). The comment notes historical inconsistency between channel name vs. ID usage.
+- **`DisplaySerialNumber` setter mutates multiple fields**:  
+  Setting `DisplaySerialNumber` on a user-added group updates `SerialNumber`, `SerialNumberConverted`, `OriginalSerialNumber`, and template names. This may cause unintended side effects if used on system-built objects.
+- **`TestTestObject.Position` setter propagates to sensors**:  
+  Changing `Position` updates *all* required sensors’ positions, but only if `Position != UserSetKey`. This may be unexpected if the UI allows switching to `UserSetKey` mid-edit.
+- **`GetNonISOTestObject()` may throw**:  
+  If no available letters/digits remain, `GetNonISOTestObject()` throws `NotSupportedException`. No fallback or logging is present.
+- **`TemplateType` may be `"?"`**:  
+  `TestObject.TestObjectType` defaults to `"?"`, and `TemplateType` inherits this. Consumers must handle this sentinel value.
+- **No explicit `INotifyPropertyChanged` implementation visible**:  
+  Classes reference `SetProperty` and `OnPropertyChanged`, but no base class (`BasePropertyChanged`) is included in the source. Behavior assumes a working implementation elsewhere.
+
+--- 
+
+*End of Documentation.*