DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/Sensors/AnalogDiagnostics.md

---
source_files:
  - Common/DTS.Common/Interface/Sensors/AnalogDiagnostics/IDiagnosticRun.cs
  - Common/DTS.Common/Interface/Sensors/AnalogDiagnostics/IDiagnosticEntry.cs
generated_at: "2026-04-16T03:05:03.996620+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "21f713440e29c323"
---

# AnalogDiagnostics

## Documentation: Analog Diagnostics Data Models

---

### 1. Purpose  
This module defines core data contract interfaces (`IDiagnosticRun` and `IDiagnosticEntry`) used to represent structured diagnostic test results for analog sensors in the DTS (Data Acquisition and Test System) platform. It serves as a standardized abstraction layer for persisting, querying, and exchanging diagnostic metadata—including run context (e.g., user, test name, pre/post-test flag) and per-sensor metrics (e.g., excitation, offset, noise, shunt)—alongside associated calibration and hardware identification. These interfaces decouple domain logic from storage or transport mechanisms, enabling consistent handling of diagnostic data across acquisition, reporting, and analysis components.

---

### 2. Public Interface  

#### `IDiagnosticRun`  
Represents a single diagnostic test run session.  
- **`long? Id { get; set; }`**  
  Optional unique identifier for the diagnostic run.  
- **`string DataPROUser { get; set; }`**  
  User identifier (e.g., login name) who initiated or performed the diagnostic run.  
- **`int? TestId { get; set; }`**  
  Optional numeric identifier for the test configuration used in this run.  
- **`string TestName { get; set; }`**  
  Human-readable name of the test configuration (e.g., `"Full Calibration"`).  
- **`bool PreTest { get; set; }`**  
  Indicates whether this run occurred *before* (`true`) or *after* (`false`) a primary calibration or procedure.  

#### `IDiagnosticEntry`  
Represents a single sensor’s diagnostic measurement within a diagnostic run.  
- **`long? Id { get; set; }`**  
  Optional unique identifier for this entry.  
- **`long DiagnosticRunId { get; set; }`**  
  Required foreign key linking this entry to its parent `IDiagnosticRun`.  
- **`double? Excitation { get; set; }`**  
  Measured excitation voltage (in volts) applied to the sensor.  
- **`DiagnosticStatus ExcitationStatus { get; set; }`**  
  Pass/fail/untested status of the excitation measurement.  
- **`double? Offset { get; set; }`**  
  Measured zero-point offset (in volts or counts, depending on sensor type).  
- **`DiagnosticStatus OffsetStatus { get; set; }`**  
  Pass/fail/untested status of the offset measurement.  
- **`double? ActualRange { get; set; }`**  
  Measured full-scale range (e.g., span in volts or counts).  
- **`DiagnosticStatus ActualRangeStatus { get; set; }`**  
  Pass/fail/untested status of the range measurement.  
- **`double? Noise { get; set; }`**  
  Measured noise level (e.g., RMS noise in microvolts).  
- **`DiagnosticStatus NoiseStatus { get; set; }`**  
  Pass/fail/untested status of the noise measurement.  
- **`double? Shunt { get; set; }`**  
  Measured shunt calibration response (e.g., in microvolts per ohm).  
- **`DiagnosticStatus ShuntStatus { get; set; }`**  
  Pass/fail/untested status of the shunt measurement.  
- **`int? SensorId { get; set; }`**  
  Optional internal numeric ID of the sensor.  
- **`string SensorSerialNumber { get; set; }`**  
  Serial number of the sensor (e.g., `"SN123456"`).  
- **`int? DASId { get; set; }`**  
  Optional internal ID of the Data Acquisition System (DAS) used.  
- **`string DASSerialNumber { get; set; }`**  
  Serial number of the DAS.  
- **`int DASChannelIdx { get; set; }`**  
  Required zero-based channel index on the DAS where the sensor was connected.  
- **`string UserCode { get; set; }`**  
  User-defined identifier for the sensor (e.g., `"SENSOR_A"`).  
- **`string UserChannelName { get; set; }`**  
  User-assigned name for the channel (e.g., `"Load Cell 1"`).  
- **`string IsoCode { get; set; }`**  
  Isolated system code (e.g., subsystem or test fixture identifier).  
- **`string IsoChannelName { get; set; }`**  
  Name of the channel within the isolated system.  
- **`double ScaleFactor { get; set; }`**  
  Required scaling factor applied to raw sensor readings (e.g., to convert to engineering units).  
- **`int CalibrationRecordId { get; set; }`**  
  Required ID referencing the calibration record used for this entry.  
- **`string CalibrationRecordXML { get; set; }`**  
  Required XML string containing full calibration parameters (e.g., coefficients, limits).  
- **`DateTime Timestamp { get; set; }`**  
  Required timestamp of when the diagnostic measurement was recorded.  

#### `DiagnosticStatus`  
Enumerated status values for diagnostic metrics.  
- **`Untested = 0`**  
  Measurement not performed (e.g., skipped or not applicable).  
- **`Passed = 1`**  
  Measurement within acceptable limits.  
- **`Failed = 2`**  
  Measurement outside acceptable limits.  

---

### 3. Invariants  
- **`DiagnosticRunId`** in `IDiagnosticEntry` is non-nullable (`long`) and must reference a valid `IDiagnosticRun.Id` (though enforcement is not specified in the interface).  
- **`DASChannelIdx`** in `IDiagnosticEntry` is non-nullable (`int`) and expected to be ≥ 0.  
- **`ScaleFactor`**, **`CalibrationRecordId`**, **`CalibrationRecordXML`**, and **`Timestamp`** in `IDiagnosticEntry` are non-nullable and must be provided.  
- **`DiagnosticStatus`** values are mutually exclusive per metric: only one of `Untested`, `Passed`, or `Failed` may apply per diagnostic parameter.  
- **`PreTest`** in `IDiagnosticRun` is a boolean flag with no default; implementations must explicitly set `true` or `false`.  

---

### 4. Dependencies  
- **Dependencies *of* this module**:  
  - `System` (used for `DateTime` in `IDiagnosticEntry`).  
- **Dependencies *on* this module**:  
  - Any component handling diagnostic data persistence (e.g., database mappers, API controllers) or analysis (e.g., reporting tools) will depend on these interfaces.  
  - Likely consumed by concrete implementations in data access layers (e.g., Entity Framework entities) or serialization layers (e.g., JSON/XML converters).  
  - *Not* referenced in the provided source, but inferred from naming conventions: `DTS.Common.Interface.Sensors` namespace suggests integration with broader sensor management modules.  

---

### 5. Gotchas  
- **`Id` properties are nullable (`long?`)** in both interfaces. This implies entries may be transient (unsaved) or use optimistic concurrency patterns, but consumers must handle `null` cases to avoid runtime errors.  
- **`CalibrationRecordXML` is a raw XML string**, not parsed or validated by the interface. Consumers must ensure XML integrity and schema compliance.  
- **`DASChannelIdx` is zero-based**, consistent with typical array indexing, but may conflict with hardware documentation using 1-based channel numbering.  
- **No validation rules are enforced by the interface itself** (e.g., range checks on `Excitation`, `Offset`, or `Noise`). Validation must be implemented externally.  
- **`IsoCode` and `IsoChannelName`** appear to represent logical grouping (e.g., test fixture), but their semantics are not documented—consumers should verify usage context.  
- **No versioning or evolution strategy is defined** for `CalibrationRecordXML`; changes to calibration schema may break deserialization.  
- **None identified from source alone.**