init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata.md

@@ -0,0 +1,79 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/ChannelGroups.cs
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/TestGraphsFields.cs
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/TestSetupFields.cs
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/TestRunMetadataFields.cs
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/TestModuleFields.cs
+  - Common/DTS.CommonCore/Enums/DTS.Viewer/TestMetadata/TestChannelFields.cs
+generated_at: "2026-04-16T02:45:19.428554+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "5089f69caf0a7cb3"
+---
+
+# Documentation: Test Metadata Enumerations
+
+## 1. Purpose  
+This module defines a set of strongly-typed enumerations that represent field names and groupings used for test metadata in the DTS Viewer system. These enums serve as standardized keys for accessing, serializing, deserializing, and querying structured metadata associated with test runs, modules, channels, graphs, and setup information. They enable type-safe handling of metadata schemas across the application—particularly in UI components, data serialization layers, and metadata validation logic—by providing a fixed set of valid field identifiers and channel group categories.
+
+## 2. Public Interface  
+
+All types are `public enum`s in the `DTS.Common.Enums.Viewer` namespace. No classes, methods, or properties are exposed.
+
+### `ChannelGroups`
+- **Members**:  
+  - `Channel`: Represents raw or physical channels.  
+  - `Graph`: Represents graph-based visualizations (likely aggregations or derived views).  
+  - `CalculatedChannel`: Represents channels whose values are computed from other channels (e.g., via formulas).  
+- **Purpose**: Categorizes channels into logical groups for filtering or UI rendering.
+
+### `TestGraphsFields`
+- **Members**:  
+  - `Name`, `HardwareChannelName`, `Channels`, `Channel`, `ChannelId`  
+- **Purpose**: Defines valid field names for objects representing test graphs (e.g., in JSON schemas or metadata structures).
+
+### `TestSetupMetadataFields`
+- **Members**:  
+  - `Name`, `DateOfTheTest`, `Graphs`, `Timestamp`, `CalibrationBehavior`  
+- **Purpose**: Specifies fields applicable to top-level test setup metadata (e.g., configuration or session-level data).
+
+### `TestRunMetadataFields`
+- **Members**:  
+  - `Id`, `Description`, `InlineSerializedData`, `Guid`, `FaultFlags`, `Software`, `SoftwareVersion`, `DataType`, `FileDate`, `FilePath`, `Modules`, `Module`, `Channels`, `CalculatedChannels`, `CalculatedChannel`  
+- **Purpose**: Defines top-level fields for a test run’s metadata, including references to nested entities (modules, channels, etc.) and runtime context.
+
+### `TestModuleFields`
+- **Members**:  
+  - Includes identifiers (`SerialNumber`, `BaseSerialNumber`, `Number`), timing (`StartRecordTimestampSec`, `TriggerTimestampSec`, etc.), sampling (`NumberOfSamples`, `UnsubsampledNumberOfSamples`, `SampleRateHz`, `StartRecordSampleNumber`), configuration (`RecordingMode`, `RequestedPreTriggerSeconds`, `AaFilterRateHz`), sensor data (`TiltSensorAxisXDegreesPre`, `TemperatureLocation1Pre`, etc.), and metadata (`InlineSerializedData`, `PTPMasterSync`).  
+- **Purpose**: Represents all known fields for a test module’s metadata, including pre/post-trigger conditions, sensor readings, and acquisition parameters.
+
+### `TestChannelFields`
+- **Members**:  
+  - Includes identifiers (`SerialNumber`, `ChannelId`, `HardwareChannelName`, `SensorId`), configuration (`Description`, `ChannelDescriptionString`, `ChannelName2`, `UnitConversion`, `LinearizationFormula`, `ZeroMethod`, `ZeroAverageWindowBegin`, `ZeroAverageWindowEnd`), calibration (`LastCalibrationDate`, `Sensitivity`, `SensitivityUnits`, `CalSignalEnabled`, `ShuntEnabled`, `MeasuredShuntDeflectionMv`, `TargetShuntDeflectionMv`), acquisition (`Start`, `IsSubsampled`, `AbsoluteDisplayOrder`, `SampleRateHz`, `UnsubsampledSampleRateHz`, `TimeOfFirstSample`), electrical properties (`ExcitationVoltage`, `MeasuredExcitationVoltage`, `FactoryExcitationVoltage`, `BridgeResistanceOhms`, `OffsetToleranceLowMv`, `OffsetToleranceHighMv`), derived values (`InitialEu`, `InitialOffset`, `UserOffsetEU`, `ScaleFactorEU`), and metadata (`IsoCode`, `UserCode`, `HIC`, `SourceModuleSerialNumber`, `Calculation`, `DataFlag`, `AtCapacity`, `SensorPolarity`, `UseEUScaler`, `T1`, `T2`).  
+- **Purpose**: Provides exhaustive field coverage for channel-level metadata, supporting both raw and calculated channels.
+
+## 3. Invariants  
+
+- **No overlap across enums**: Each enum defines a distinct set of field names for a specific metadata entity (e.g., `TestChannelFields` vs. `TestModuleFields`). There is no guarantee of uniqueness across enums (e.g., `Name`, `Channels`, `Module` appear in multiple enums), but within each enum, all members are unique.  
+- **Field names are string-literal keys**: These enums are intended to map to string-based keys (e.g., in JSON or dictionaries). Their values are implicitly `int`-backed, but the *semantic meaning* comes from their *names*, not their numeric values.  
+- **No ordering guarantees**: The enums are not ordered by importance, hierarchy, or sequence. `AbsoluteDisplayOrder` in `TestChannelFields` is a *field name*, not an ordering directive for the enum itself.  
+- **No validation logic**: These are *pure data definitions*; no runtime validation or constraints are enforced by the enums themselves.
+
+## 4. Dependencies  
+
+- **Internal usage**: These enums are defined in `DTS.CommonCore`, indicating they are part of a shared common library. They are likely consumed by:  
+  - UI components (e.g., metadata viewers, configuration panels)  
+  - Serialization/deserialization logic (e.g., JSON converters, DTOs)  
+  - Metadata querying or filtering systems  
+- **No external dependencies**: The source files contain no `using` statements, implying no dependencies on other project types or external libraries. They rely solely on the base .NET runtime.
+
+## 5. Gotchas  
+
+- **Ambiguity in field semantics**: While enum names are precise, their *intended usage* (e.g., whether `Channels` in `TestGraphsFields` refers to a list or a single channel) is not clarified by the enum alone. Context (e.g., JSON schema or usage site) is required.  
+- **Redundant field names across enums**: Fields like `Module`, `Channels`, `CalculatedChannel`, `Name`, and `ChannelId` appear in multiple enums (`TestRunMetadataFields`, `TestSetupMetadataFields`, `TestGraphsFields`, `TestChannelFields`). This may indicate shared schema concepts but risks misuse if enums are used interchangeably.  
+- **No deprecation markers**: The enums do not indicate obsolete or legacy fields (e.g., `ChannelName2`, `UserChannelName`, `UserCode`), which may complicate maintenance or migration.  
+- **Tilt/temperature fields assume pre/post sensor states**: `TestModuleFields` includes many `Pre`/`Post`-suffixed fields (e.g., `TiltSensorAxisXDegreesPre`, `TemperatureLocation4Post`). This implies a rigid assumption about test procedures involving pre/post events; deviations may cause misinterpretation.  
+- **No documentation on `InlineSerializedData`**: Its purpose (e.g., binary vs. JSON, encoding) is not evident from the enum alone.  
+
+None identified beyond the above ambiguities and design assumptions.