init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/Hardware/AddEditHardware.md

@@ -0,0 +1,133 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Hardware/AddEditHardware/IAddEditHardwareView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/AddEditHardware/IAddEditHardwareDASModule.cs
+  - Common/DTS.CommonCore/Interface/Hardware/AddEditHardware/IAddEditHardwareViewModel.cs
+  - Common/DTS.CommonCore/Interface/Hardware/AddEditHardware/IAddEditHardwareHardware.cs
+generated_at: "2026-04-16T02:30:45.767318+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "8c9d2e027679c71f"
+---
+
+# Documentation: AddEditHardware Module Interface
+
+## 1. Purpose  
+This module provides the interface layer for a UI-driven hardware configuration and editing workflow—specifically for adding or editing DAS (Data Acquisition System) hardware units and their associated modules in the SLICE6 ecosystem. It defines contracts for the view, view model, hardware model, and DAS module representations, enabling separation of concerns between UI presentation and business logic while supporting both physical hardware and "stand-in" (placeholder) entries. The module integrates with the broader diagnostics and hardware list subsystems, and supports persistence via conversion to `IISOHardware`.
+
+## 2. Public Interface  
+
+### `IAddEditHardwareView`  
+- **`void Activated();`**  
+  Notifies the view it has been activated; the view should perform any post-activation initialization or UI updates.  
+- **`int ViewDbVersion { get; set; }`**  
+  Gets or sets the database version associated with the view’s current data context; likely used for concurrency or versioning checks during save.
+
+### `IAddEditHardwareDASModule`  
+- **`HardwareTypes ModuleType { get; set; }`**  
+  Gets or sets the type of the DAS module (e.g., analog input, digital I/O).  
+- **`string SerialNumber { get; set; }`**  
+  Gets or sets the serial number of the module.  
+- **`ImageSource DASImage { get; }`**  
+  Gets an image (WPF `ImageSource`) representing the module visually.  
+- **`IAddEditHardwareHardware OwningHardware { get; set; }`**  
+  Gets or sets the parent hardware unit that owns this module.  
+- **`SLICEBridgeTypes SLICEBridgeType { get; set; }`**  
+  Gets or sets the bridge type used by the module (e.g., for SLICE6 connectivity).  
+- **`string GetSerialNumberPrefix();`**  
+  Returns the expected prefix for serial numbers of modules of this `ModuleType`; used for validation.
+
+### `IAddEditHardwareViewModel`  
+- **`IAddEditHardwareView View { get; set; }`**  
+  Gets or sets the associated view instance (MVVM pattern).  
+- **`void Unset();`**  
+  Cleans up references and state, typically called when the view model is being discarded.  
+- **`IAddEditHardwareHardware Hardware { get; set; }`**  
+  Gets or sets the hardware instance being edited or added.  
+- **`int? TestId { get; set; }`**  
+  Gets or sets an optional test ID associated with the hardware (e.g., for test-specific configuration).  
+- **`void SetHardware(IDASHardware hw, IISOHardware isoHW);`**  
+  Initializes the view model with existing hardware data from the diagnostics (`IDASHardware`) and ISO layer (`IISOHardware`).  
+- **`bool NotificationsOn { get; set; }`**  
+  Enables or disables change notifications (e.g., to suppress UI updates during bulk initialization).  
+- **`bool Validate(IISOHardware isoHW, ref List<string> errors, ref List<string> warnings, bool displayWindow, bool IsAdd);`**  
+  Validates the current hardware state against `isoHW`. Returns `true` if valid; populates `errors` and `warnings` lists. If `displayWindow` is `true`, may show UI dialogs for warnings/errors. `IsAdd` indicates if this is a new hardware entry.  
+- **`void Save();`**  
+  Commits changes made in the view model to persistent storage (e.g., database).  
+- **`IISOHardware GetISOHardware();`**  
+  Returns the current hardware state as an `IISOHardware` instance (used for persistence or propagation to other layers).  
+- **`bool AllowStandin { get; set; }`**  
+  Gets or sets whether "stand-in" (non-physical) hardware entries are permitted.  
+- **`void SetSLICE6TreeView(ISLICE6TreeView treeView, IHardwareListViewModel treeViewModel);`**  
+  Injects references to the SLICE6 tree view and its view model for integration (e.g., updating tree selection or state).  
+- **`ISLICE6TreeView SLICE6TreeView { get; }`**  
+  Gets the currently assigned SLICE6 tree view instance.
+
+### `IAddEditHardwareHardware`  
+- **`HardwareTypes HardwareType { get; set; }`**  
+  Gets or sets the type of the DAS hardware unit.  
+- **`string SerialNumber { get; set; }`**  
+  Gets or sets the serial number of the hardware unit.  
+- **`string FirmwareVersion { get; set; }`**  
+  Gets or sets the firmware version of the hardware unit.  
+- **`string IPAddress { get; set; }`**  
+  Gets or sets the IP address (if supported).  
+- **`bool SupportsIPAddress { get; }`**  
+  Indicates whether the hardware type supports IP addressing.  
+- **`bool SupportsRackSize { get; }`**  
+  Indicates whether the hardware type supports rack size configuration.  
+- **`bool SupportsConfiguration { get; }`**  
+  Indicates whether the hardware type supports SLICE configuration options.  
+- **`SLICEConfigurations SLICEConfiguration { get; set; }`**  
+  Gets or sets the SLICE configuration (e.g., rack layout, module positions).  
+- **`RackSizes RackSize { get; set; }`**  
+  Gets or sets the rack size (e.g., 1U, 2U).  
+- **`ImageSource DASImage { get; }`**  
+  Gets an image representing the hardware unit visually.  
+- **`ObservableCollection<IAddEditHardwareDASModule> Modules { get; set; }`**  
+  Gets or sets the collection of modules installed in the hardware unit.  
+- **`void RemoveModule(IAddEditHardwareDASModule module);`**  
+  Removes a module from the `Modules` collection.  
+- **`void AddModule();`**  
+  Adds a new module instance to the `Modules` collection (implementation likely creates a default module of appropriate type).  
+- **`IISOHardware ToISOHardware();`**  
+  Converts the current state into an `IISOHardware` instance for persistence or external use.  
+- **`bool StandIn { get; set; }`**  
+  Indicates whether this entry represents placeholder/stand-in hardware (not physical).  
+- **`bool IsModule { get; set; }`**  
+  Indicates whether this instance represents a module (vs. a top-level hardware unit).  
+- **`bool IsAdd { get; set; }`**  
+  Indicates whether this hardware record is new (`true`) or pre-existing (`false`).
+
+## 3. Invariants  
+- **`HardwareType` and `ModuleType` must be valid enum values** from `DTS.Common.Enums.Hardware.HardwareTypes` and `DTS.Common.Enums.Hardware.SLICEBridgeTypes`, respectively.  
+- **`Modules` collection must be initialized before use** (via `ObservableCollection<IAddEditHardwareDASModule>`), as `AddModule()` and `RemoveModule()` assume non-null.  
+- **`DASImage` is read-only** (`get` only) for both `IAddEditHardwareHardware` and `IAddEditHardwareDASModule`; images must be set internally (e.g., via constructor or factory).  
+- **`IsAdd` must be set before validation or save**, as `Validate()` uses it to determine behavior (e.g., uniqueness checks).  
+- **`StandIn` and `IsModule` are mutually orthogonal flags**—a hardware unit can be `StandIn == true` and `IsModule == false`, or vice versa.  
+- **`ViewDbVersion` must be synchronized with the underlying database version** during activation and save operations to prevent stale writes.
+
+## 4. Dependencies  
+- **Depends on**:  
+  - `DTS.Common.Base` (`IBaseView`, `IBaseViewModel`)  
+  - `DTS.Common.Interface.DASFactory.Diagnostics` (`IDASHardware`, `IISOHardware`)  
+  - `DTS.Common.Interface.DASFactory.Diagnostics.HardwareList` (`IHardwareListViewModel`, `ISLICE6TreeView`)  
+  - `DTS.Common.Interface.DataRecorders` (likely for ISO layer integration)  
+  - `DTS.Common.Enums.Hardware` (`HardwareTypes`, `SLICEBridgeTypes`, `SLICEConfigurations`, `RackSizes`)  
+  - WPF UI types (`System.Windows.Media.ImageSource`)  
+- **Depended on by**:  
+  - UI layer implementations (e.g., WPF views and view models) for hardware configuration.  
+  - Persistence layers that consume `IISOHardware` (via `ToISOHardware()` and `GetISOHardware()`).  
+  - SLICE6 tree view integrations (`SetSLICE6TreeView()` suggests coupling with `HardwareListViewModel`).
+
+## 5. Gotchas  
+- **`DASImage` is read-only**—consumers cannot assign images directly; initialization must occur in concrete implementations (e.g., via factory or constructor).  
+- **`NotificationsOn` is a blunt instrument**—disabling it suppresses *all* change notifications, which may mask unintended side effects if not carefully managed around initialization.  
+- **`Validate()` mutates `errors` and `warnings` via `ref`**—callers must initialize these lists before invoking.  
+- **`AddModule()` does not specify module type**—implementation likely infers type from `HardwareType` or defaults to a generic module, which may cause ambiguity.  
+- **`IsAdd` and `IsModule` are both `bool` properties**—no validation ensures `IsModule == true` implies `IsAdd == false` (or vice versa); logic may rely on external context.  
+- **`GetSerialNumberPrefix()` is not guaranteed to return a non-empty string**—callers should handle empty/whitespace prefixes.  
+- **No explicit thread-safety guarantees**—all interfaces assume single-threaded UI access (common in WPF MVVM but not stated).  
+- **`StandIn` hardware may lack full functionality**—e.g., `ToISOHardware()` may produce incomplete or placeholder data.  
+
+*None identified from source alone.*

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/Hardware/HardwareList.md

@@ -0,0 +1,239 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/ISLICE6TreeView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardwareListView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardwareListSelectView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardwareListOverdueView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardwareListReplaceView.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/ISLICE6TreeNode.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardware.cs
+  - Common/DTS.CommonCore/Interface/Hardware/HardwareList/IHardwareListViewModel.cs
+generated_at: "2026-04-16T02:31:10.910753+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "0b794dc751ea2075"
+---
+
+# HardwareList
+
+## Documentation: Hardware List Module (DTS.Common.Interface.DASFactory.Diagnostics.HardwareList)
+
+---
+
+### 1. Purpose
+
+This module defines the interface layer for the *Hardware List* feature within the DASFactory diagnostics subsystem. It provides a set of strongly-typed interfaces that abstract the presentation and data models for viewing, filtering, selecting, and managing hardware devices (e.g., DAS units, SLICE6 modules, bridges) in a diagnostic context. The interfaces support multiple specialized views (e.g., overdue calibration, replacement, SLICE6 tree), and the central `IHardwareListViewModel` orchestrates data retrieval, state management, and user interactions—including calibration tracking, sample rate configuration, clock synchronization (PTP), and hardware association (e.g., SLICE6 units to SLICE6DB backbones). It serves as the contract between the UI layer and underlying business logic for hardware inventory and configuration.
+
+---
+
+### 2. Public Interface
+
+#### Interfaces (View Contracts)
+
+- **`ISLICE6TreeView : IBaseView`**  
+  Represents the view contract for the SLICE6 tree hierarchy display.
+
+- **`IHardwareListView : IBaseView`**  
+  Represents the view contract for the primary hardware list display.
+
+- **`IHardwareListSelectView : IBaseView`**  
+  Represents the view contract for hardware selection workflows.
+
+- **`IHardwareListOverdueView : IBaseView`**  
+  Represents the view contract for displaying hardware with overdue calibration.
+
+- **`IHardwareListReplaceView : IBaseView`**  
+  Represents the view contract for hardware replacement workflows.
+
+#### Data Model Interfaces
+
+- **`ISLICE6TreeNode`**  
+  Represents a SLICE6 unit node in a tree structure.  
+  - `int DASId { get; set; }`  
+  - `string SerialNumber { get; set; }`  
+  - `int Port { get; set; }`  
+  - `string PortString { get; }` *(read-only)*  
+  - `int Number { get; set; }`  
+  - `int PositionOnChain { get; set; }`  
+  - `string PositionOnChainString { get; }` *(read-only)*  
+
+- **`IHardware`**  
+  Represents a hardware device (e.g., DAS, SLICE6, bridge).  
+  - `int DASId { get; set; }`  
+  - `bool Disabled { get; set; }`  
+  - `bool Included { get; set; }`  
+  - `double TestSampleRate { get; set; }`  
+  - `string SerialNumber { get; set; }`  
+  - `string HardwareType { get; set; }`  
+  - `string ChannelCount { get; set; }`  
+  - `string Firmware { get; set; }`  
+  - `double? MaxSampleRate { get; set; }`  
+  - `DateTime? CalDate { get; set; }`  
+  - `DateTime? CalDueDate { get; set; }`  
+  - `object Hardware { get; set; }` *(opaque reference to underlying hardware object)*  
+  - `void SetIncluded(bool bIncluded)`  
+  - `void SetMixedRates(bool mixed)`  
+  - `bool Filter(string term)`  
+  - `string ParentDAS { get; set; }`  
+  - `int PositionOnChain { get; set; }`  
+  - `int PositionOnDistributor { get; set; }`  
+  - `int Port { get; set; }`  
+  - `int AnalogChannels { get; set; }`  
+  - `int SquibChannels { get; set; }`  
+  - `int DigitalInChannels { get; set; }`  
+  - `int DigitalOutChannels { get; set; }`  
+  - `int UartChannels { get; set; }`  
+  - `int StreamOutChannels { get; set; }`  
+  - `int StreamInChannels { get; set; }`  
+  - `void DetermineChannelCount(bool showCompact, IHardware[] allHardware)`  
+  - `string IPAddress { get; set; }`  
+  - `DateTime? FirstUseDate { get; set; }`  
+  - `bool IsFirstUseValid { get; set; }`  
+  - `bool IsTSRAIR { get; }`  
+  - `byte PTPDomainID { get; set; }`  
+
+#### View Model Interface
+
+- **`IHardwareListViewModel : IBaseViewModel, IFilterableListView`**  
+  Central view model for hardware list operations. Key members:
+
+  - **Properties**
+    - `ISLICE6TreeNode SelectedSLICE6 { get; set; }`
+    - `ISLICE6TreeNode[] AvailableSLICE6 { get; set; }`
+    - `IHardware SelectedSLICE6DB { get; set; }`
+    - `IHardware[] AvailableSLICE6DB { get; set; }`
+    - `bool IsEdit { get; set; }`
+    - `int TDASCalPeriod`, `int G5CalPeriod`, ..., `int SLICE6AirBridge_CalPeriod`  
+      *(Calibration period defaults for each hardware type)*
+    - `IHardwareListReplaceView ReplaceView { get; set; }`
+    - `IHardwareListView View { get; set; }`
+    - `IHardwareListOverdueView OverdueView { get; set; }`
+    - `IHardwareListSelectView SelectView { get; set; }`
+    - `ISLICE6TreeView SLICE6TreeView { get; set; }`
+    - `IHardware[] Hardware { get; set; }`
+    - `IHardware[] OverdueHardware { get; set; }`
+    - `IHardware[] HardwareInTest { get; set; }`
+    - `IHardware HardwareToReplace { get; set; }`
+    - `IHardware[] AvailableHardware { get; set; }`
+    - `IHardware ReplacementHardware { get; set; }`
+    - `bool ShowCompact { get; set; }`
+    - `ISLICE6TreeNode[] SLICE6TreeNodes { get; set; }`
+    - `int TestAAFRateHzColumnWidth`, `TestSampleRateColumnWidth`, `TestClockMasterColumnWidth`, `PTPDomainColumnWidth { get; set; }`
+
+  - **Methods**
+    - `void InitializeReplace(ITestSetup setup, IsoViewMode viewMode)`  
+      Initializes the replacement view for a given test.
+    - `void GetHardware(bool bIncludeModules, bool bIncludeOverdue, bool bIncludeBridges, int? testId, int? groupId)`  
+      Loads hardware data based on filters.
+    - `void GetAvailableSampleRates(int[] availableSampleRates)`  
+      Populates available sample rates (likely for UI dropdowns).
+    - `void SetTestSampleRates(Dictionary<string, double> testSampleRates)`  
+      Sets per-hardware sample rates for the current test.
+    - `void SetHasIncludedChildren()`  
+      Updates state indicating if any hardware has included children.
+    - `void UpdateTestSampleRate(string childSerialNumber, double testSampleRate)`  
+      Updates sample rate for a specific child device.
+    - `void SetTestAAFRates(Dictionary<string, float> testAAFRates)`  
+      Sets per-hardware anti-aliasing filter rates.
+    - `void UpdateTestAAFilterRate(string childSerialNumber, float testAAFilterRate)`  
+      Updates AAF rate for a specific child device.
+    - `Func<SerializableAAF.DAS_TYPE, int, float> GetAAFForHardwareFunc { get; set; }`  
+      Callback to compute AAF rate for a given hardware type and sample rate.
+    - `void CheckForMixedDAS(string nonParentSerialNumber, double testSampleRate)`  
+      Validates sample rate consistency across parent/child DAS units.
+    - `void SetParentMixedRates(string parentDAS, bool mixedRates)`  
+      Marks a parent DAS as having mixed sample rates.
+    - `void SetTestClockProfiles(DTS.Common.ClockSyncProfile masterProfile, DTS.Common.ClockSyncProfile slaveProfile)`  
+      Sets clock sync profiles for master/slave configuration.
+    - `void SetTestClockMasters(Dictionary<string, bool> testClockMasters)`  
+      Sets per-device clock master status.
+    - `void UpdateTestClockMaster(string childSerialNumber, bool testClockMaster)`  
+      Updates clock master status for a device.
+    - `void SetTestPTPDomainIDs(Dictionary<string, byte> testPTPDomainIDs)`  
+      Sets per-device PTP domain IDs.
+    - `void UpdateTestPTPDomainID(string childSerialNumber, byte ptpDomainId)`  
+      Updates PTP domain ID for a device.
+    - `void Unset()`  
+      Clears view model state.
+    - `void Sort(object o, bool columnClick)`  
+      Sorts main hardware list.
+    - `void SortOverdue(object o, bool columnClick)`  
+      Sorts overdue hardware list.
+    - `void SetIncluded(string[] serialNumbers, bool included)`  
+      Sets `Included` flag for multiple devices by serial number.
+    - `void SetIncluded(int[] dasId)`  
+      Sets `Included` flag for multiple devices by DAS ID.
+    - `void Filter(string term)`  
+      Applies text filter to hardware list.
+    - `void MouseDoubleClick(int index)`  
+      Handles double-click on list item at `index`.
+    - `void SetCache(IISOHardware[] hardware)`  
+      Populates internal cache from raw hardware data.
+    - `void LoadTreeView(string serialNumber)`  
+      Loads SLICE6 tree for a given SLICE6DB serial number.
+    - `void Associate(ISLICE6TreeNode node)`  
+      Associates a SLICE6 node with the currently selected SLICE6DB (no commit).
+    - `void Associate(IHardware node)`  
+      Associates units from one SLICE6DB with another (no commit).
+    - `void UnAssociate(ISLICE6TreeNode node)`  
+      Removes association of a SLICE6 node from its SLICE6DB (no commit).
+    - `void SaveSLICE6Associations(string serialNumber)`  
+      Commits pending SLICE6/SLICE6DB associations for a given SLICE6DB.
+    - `IHardware[] GetSelectedItems()`  
+      Returns currently selected hardware items.
+    - `void Replace()`  
+      Executes hardware replacement (`HardwareToReplace` → `ReplacementHardware`).
+    - `void SetCalPeriods(...)`  
+      Sets calibration period defaults for all hardware types.
+
+---
+
+### 3. Invariants
+
+- All hardware objects (`IHardware`) must have a non-null `SerialNumber`.
+- `CalDueDate` is derived from `CalDate` + hardware-specific calibration period (e.g., `SLICE6_CalPeriod`).
+- `ChannelCount` is computed dynamically via `DetermineChannelCount()` and reflects channel composition (e.g., `AnalogChannels`, `SquibChannels`, etc.).
+- `IsFirstUseValid` and `FirstUseDate` are only meaningful for hardware supporting first-use tracking (e.g., 15524 DAS).
+- `SLICE6TreeNodes` is populated only after `LoadTreeView()` is called.
+- `SLICE6TreeNodes` contains *all* SLICE6 units associated with the selected `SelectedSLICE6DB`.
+- Association operations (`Associate`, `UnAssociate`) are *not* persisted until `SaveSLICE6Associations()` is invoked.
+- `HardwareToReplace` and `ReplacementHardware` must both be non-null before calling `Replace()`.
+- `TestSampleRate` on a child device must be compatible with its parent’s rate (enforced via `CheckForMixedDAS()`).
+- `PTPDomainID` is a per-device setting; domain conflicts may occur if not managed.
+
+---
+
+### 4. Dependencies
+
+- **Internal Dependencies**  
+  - `DTS.Common.Base` (provides `IBaseView`, `IBaseViewModel`, `IFilterableListView`)  
+  - `DTS.Common.Classes.Hardware` (likely contains `IISOHardware` used in `SetCache`)  
+  - `DTS.Common.Enums` (e.g., `IsoViewMode` used in `InitializeReplace`)  
+  - `DTS.Common.Interface.Pagination` (via `IFilterableListView`)  
+  - `DTS.Common.Interface.TestSetups.TestSetupsList` (e.g., `ITestSetup` used in `InitializeReplace`)  
+  - `SerializableAAF` (namespace for `DAS_TYPE` enum used in `GetAAFForHardwareFunc`)
+
+- **External Dependencies**  
+  - UI framework (e.g., WPF or WinForms) for `IBaseView` implementations.  
+  - Backend services for hardware data persistence (implied by `GetHardware`, `SaveSLICE6Associations`).
+
+- **Depended Upon**  
+  - UI layer implementations (e.g., `SLICE6TreeView`, `HardwareListViewModel`) depend on these interfaces for binding and decoupling.
+
+---
+
+### 5. Gotchas
+
+- **`Hardware` property**: The `object Hardware { get; set; }` field is typed as `object`, implying tight coupling to concrete types elsewhere (e.g., `DAS`, `SLICE6`). This may complicate mocking or testing without access to concrete implementations.
+- **`DetermineChannelCount` behavior**: The `showCompact` parameter suppresses SLICEPro units connected to ECMs. This may cause confusion if the UI toggles this flag without clear user indication.
+- **`IsFirstUseValid` semantics**: `FirstUseDate` is only valid *if* `IsFirstUseValid` is `true`. A `null` `FirstUseDate` does *not* imply invalidity—it may mean "not yet used since calibration."
+- **Association workflow**: `Associate`/`UnAssociate` do *not* commit changes. Developers may mistakenly assume they persist data. `SaveSLICE6Associations()` must be called explicitly.
+- **`GetAAFForHardwareFunc`**: This callback is a `Func<SerializableAAF.DAS_TYPE, int, float>`—its implementation must be provided externally. Its purpose (computing AAF rate) is documented, but the mapping logic is not defined here.
+- **`SLICE6TreeNodes` vs `AvailableSLICE6`**:  
+  - `SLICE6TreeNodes`: *All* SLICE6 units associated with the current `SelectedSLICE6DB` (set by `LoadTreeView`).  
+  - `AvailableSLICE6`: SLICE6 units *not* associated with the current `SelectedSLICE6DB`.  
+  Confusing these may lead to incorrect UI behavior.
+- **`TestSampleRate` vs `MaxSampleRate`**: `TestSampleRate` is user-configurable per device; `MaxSampleRate` is a hardware limit. No validation is defined in the interface to prevent exceeding `MaxSampleRate`.
+- **`PTPDomainID`**: No range validation is specified (e.g., 0–237 per IEEE 1588). Implementation must enforce constraints.
+
+None identified beyond these.