init

enriched-partialglm/Common/DTS.Common.Import/Interfaces.md

@@ -0,0 +1,174 @@
+---
+source_files:
+  - Common/DTS.Common.Import/Interfaces/IPersistImport.cs
+  - Common/DTS.Common.Import/Interfaces/IParseImport.cs
+  - Common/DTS.Common.Import/Interfaces/IParseVariant.cs
+  - Common/DTS.Common.Import/Interfaces/IParseCSVTest.cs
+  - Common/DTS.Common.Import/Interfaces/IParseCSVSensor.cs
+  - Common/DTS.Common.Import/Interfaces/ICalibrationImport.cs
+  - Common/DTS.Common.Import/Interfaces/ILockImport.cs
+  - Common/DTS.Common.Import/Interfaces/IGroupImport.cs
+generated_at: "2026-04-16T11:46:21.980624+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "4d7a3572ba82cd30"
+---
+
+# DTS.Common.Import Interfaces Documentation
+
+## 1. Purpose
+
+This module defines the core abstraction layer for the DTS import subsystem. It provides interfaces for parsing import files (CSV, variants), persisting imported data, managing database locks during concurrent imports, handling sensor calibration records, and organizing sensors into test groups. These interfaces establish the contract between import data sources and the domain model, enabling extensibility for different import formats and workflows.
+
+---
+
+## 2. Public Interface
+
+### IPersistImport
+**Signature:**
+```csharp
+public interface IPersistImport
+{
+    void Save();
+}
+```
+**Behavior:** Persists the imported data. Implementations are expected to commit the import state to a data store.
+
+---
+
+### IParseImport
+**Signature:**
+```csharp
+public interface IParseImport
+{
+    ImportObject Parse(IEnumerable<string> importFiles);
+}
+```
+**Behavior:** Accepts a collection of file paths and returns a populated `ImportObject` representing the parsed import data.
+
+---
+
+### IParseVariant
+**Signature:**
+```csharp
+public interface IParseVariant
+{
+    string FileName { get; set; }
+    void Parse(ref ImportObject importObject);
+}
+```
+**Behavior:** Parses variant-specific import data. The `FileName` property indicates the source file. The `Parse` method modifies the passed `ImportObject` by reference.
+
+---
+
+### IParseCSVTest
+**Signature:**
+```csharp
+public interface IParseCSVTest
+{
+    int Version { get; }
+    void ParseVersion(CsvReader csvReader, TestSetupImportData tsid);
+}
+```
+**Behavior:** Handles versioned CSV test setup parsing. `Version` indicates the parser version supported. `ParseVersion` reads from a `CsvReader` and populates `TestSetupImportData`.
+
+---
+
+### IParseCSVSensor
+**Signature:**
+```csharp
+public interface IParseCSVSensor
+{
+    int Version { get; }
+    void Initialize(ICalibrationImport import, ZeroMethodOptions zmOptions,
+        IImportNotification importNotification, bool importCreateDynamicGroups,
+        bool useIsoCodeFilterMapping, bool useZeroForUnfiltered);
+    void ParseVersion(CSVImportTags.Tags field, string val, ParseParameters pp);
+}
+```
+**Behavior:** Handles versioned CSV sensor parsing. `Initialize` must be called to configure calibration handling, zero method options, notification callbacks, and filtering options before parsing. `ParseVersion` processes individual field/value pairs using `ParseParameters`.
+
+---
+
+### ICalibrationImport
+**Signature:**
+```csharp
+public interface ICalibrationImport
+{
+    SensorCalibration AddLinearCalRecordIfNeeded(SensorCalibration sc, bool savedIsProportional, bool savedRemoveOffset);
+    SensorCalibration AddLinearZeroMethodIfNeeded(SensorCalibration sc, ZeroMethodType zeroMethodType, double zeroMethodStart, double zeroMethodEnd);
+    SensorCalibration CheckForExcitationCalibration(SensorCalibration sc, double sensitivity, ExcitationVoltageOptions.ExcitationVoltageOption excitation, string EU);
+}
+```
+**Behavior:** Manages sensor calibration during import. Methods conditionally add calibration records (linear calibration, zero method, excitation calibration) to a `SensorCalibration` object and return the modified instance.
+
+---
+
+### ILockImport
+**Signature:**
+```csharp
+public interface ILockImport
+{
+    bool Contended { get; }
+    void SetLock(ref ImportObject importObject, ref StringBuilder message);
+    void FreeLock(ref ImportObject importObject);
+    bool StealLock(bool proceed);
+}
+```
+**Behavior:** Manages database locks during import operations. `Contended` indicates whether lock contention exists. `SetLock` acquires a lock and populates the `message` StringBuilder with any errors. `FreeLock` releases the lock. `StealLock` forcibly takes a lock if `proceed` is true.
+
+---
+
+### IGroupImport
+**Signature:**
+```csharp
+public interface IGroupImport
+{
+    ParseParameters ParseParameters { get; set; }
+    Tuple<TestTemplate, List<IGroup>> CreateGroups(List<SensorData> sensors, Dictionary<string, List<TsetSetupImportSensorInfo>> groupSensorLookup, TestTemplate testTemplate, bool createDynamicGroups, List<IGroup> staticGroups, Action<double> setProgress);
+    Dictionary<string, List<TsetSetupImportSensorInfo>> GetGroupSensorLookup(List<SensorData> sensors, Dictionary<string, string> sensorGroupNameLookup, Dictionary<string, List<string>> groupNameSensorListLookup);
+}
+```
+**Behavior:** Creates and manages sensor groupings during import. `GetGroupSensorLookup` builds a lookup dictionary mapping group names to sensor info. `CreateGroups` generates test groups (dynamic and/or static) and returns a tuple of the test template and group list. Progress reporting is supported via the `setProgress` callback.
+
+---
+
+## 3. Invariants
+
+- **IParseCSVSensor initialization ordering:** The `Initialize` method must be called before `ParseVersion` can be meaningfully executed (inferred from parameter dependencies).
+- **ILockImport message sharing:** The `StringBuilder message` parameter in `SetLock` is documented as shared between all types and accumulates all database lock errors.
+- **IParseVariant ref semantics:** The `ImportObject` is passed by reference, implying the parser is expected to modify the existing object rather than replace it.
+- **ILockImport.Contended:** Must return `true` if the internal collection of contended locks has any items (per source comment).
+
+---
+
+## 4. Dependencies
+
+### This module depends on:
+- `System.Collections.Generic` (IEnumerable, Dictionary, List)
+- `System.Text` (StringBuilder)
+- `System` (Tuple, Action)
+- `CsvHelper` (CsvReader)
+- `DTS.Common.Classes` (TestSetupImportData)
+- `DTS.Common.Classes.Sensors` (SensorData)
+- `DTS.Common.Enums` (ExcitationVoltageOptions)
+- `DTS.Common.Enums.Sensors` (ZeroMethodType, ZeroMethodOptions)
+- `DTS.Common.Import.ImportOptions` (CSVImportTags, ParseParameters)
+- `DTS.Common.Interface.Groups.GroupList` (IGroup)
+- `DTS.SensorDB` (SensorCalibration)
+- `DataPROWin7.DataModel` (TestTemplate, TsetSetupImportSensorInfo)
+
+### What depends on this module:
+- Not determinable from the provided source files alone (these are interface definitions).
+
+---
+
+## 5. Gotchas
+
+1. **ILockImport error message accumulation:** The `message` StringBuilder in `SetLock` is shared across all lock types. Errors accumulate, so callers should check the message contents after all lock operations complete rather than after each individual call.
+
+2. **FB 36740 reference:** The `ILockImport` interface has a comment referencing "FB 36740" for database lock support. This appears to be a feature/bug tracking reference that may provide historical context for the locking implementation.
+
+3. **IParseVariant ref parameter:** The use of `ref` for `ImportObject` in `Parse` is unusual for an interface pattern. Callers should be aware the object may be mutated in place.
+
+4. **IParseCSVSensor.Initialize complexity:** The `Initialize` method accepts 6 parameters including flags for `importCreateDynamicGroups`, `useIsoCodeFilterMapping`, and `useZeroForUnfiltered`. The interaction between these flags and the parsing behavior is not documented in the interface.