DP44/enriched-qwen3-coder-next/DataPRO/DbAPI/TestMetaData.md

---
source_files:
  - DataPRO/DbAPI/TestMetaData/ICustomerDetails.cs
  - DataPRO/DbAPI/TestMetaData/ILabratoryDetails.cs
  - DataPRO/DbAPI/TestMetaData/ITestEngineerDetails.cs
  - DataPRO/DbAPI/TestMetaData/CustomerDetails.cs
  - DataPRO/DbAPI/TestMetaData/TestEngineerDetails.cs
  - DataPRO/DbAPI/TestMetaData/LabratoryDetails.cs
generated_at: "2026-04-16T04:25:29.306320+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "440dcd3555714b4f"
---

# Test Metadata Database API Module Documentation

## 1. Purpose

This module provides a standardized database abstraction layer for CRUD operations on three core metadata entity types—Customer, Laboratory, and Test Engineer details—within the system's database. It encapsulates direct SQL Server interactions via stored procedures (`sp_*`) and enforces user authentication, error handling, and connection management. The module exists to decouple business logic from low-level data access, ensuring consistent error reporting (via `ulong` return codes), centralized logging, and reuse of common database patterns across the application.

## 2. Public Interface

All interfaces reside in the `DbAPI.TestMetaData` namespace (e.g., `ICustomerDetails`, `ILabratoryDetails`, `ITestEngineerDetails`). Implementation classes (`CustomerDetails`, `LabratoryDetails`, `TestEngineerDetails`) are internal and implement their respective interfaces.

### `ICustomerDetails`

- **`ulong CustomerDetailsInsert(IUserDbRecord user, IConnectionDetails connection, CustomerDetailsDbRecord customerDetailsDbRecord, out int newId, out string errorString)`**  
  Inserts a new record into the `CustomerDetails` table via `sp_CustomerDetailsInsert`. Returns `ERROR_SUCCESS` (0) on success; `newId` holds the generated ID. `errorString` may contain SP-level error details.

- **`ulong CustomerDetailsUpdate(IUserDbRecord user, IConnectionDetails connection, CustomerDetailsDbRecord customerDetailsDbRecord, out string errorString)`**  
  Updates an existing `CustomerDetails` record via `sp_CustomerDetailsUpdate`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

- **`ulong CustomerDetailsGet(IUserDbRecord user, IConnectionDetails connection, string name, out ICustomerDetailsDbRecord[] customerDetailsDbRecords)`**  
  Retrieves all `CustomerDetails` records matching the `name` filter via `sp_CustomerDetailsGet`. Returns `ERROR_SUCCESS` on success; `customerDetailsDbRecords` is an array of valid (non-`IsInvalidBlank()`) records, or `null` if none found.

- **`ulong CustomerDetailsDelete(IUserDbRecord user, IConnectionDetails connection, string name, out string errorString)`**  
  Deletes `CustomerDetails` records matching `name` via `sp_CustomerDetailsDelete`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

### `ILabratoryDetails`

- **`ulong LabratoryDetailsInsert(IUserDbRecord user, IConnectionDetails connection, LabratoryDetailsDbRecord labratoryDetailsDbRecord, out int newId, out string errorString)`**  
  Inserts a new `LabratoryDetails` record via `sp_LabratoryDetailsInsert`. Returns `ERROR_SUCCESS` on success; `newId` holds the generated ID. `errorString` may contain SP-level error details.

- **`ulong LabratoryDetailsUpdate(IUserDbRecord user, IConnectionDetails connection, LabratoryDetailsDbRecord labratoryDetailsDbRecord, out string errorString)`**  
  Updates an existing `LabratoryDetails` record via `sp_LabratoryDetailsUpdate`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

- **`ulong LabratoryDetailsUpdateInsert(IUserDbRecord user, IConnectionDetails connection, LabratoryDetailsDbRecord labratoryDetailsDbRecord, out string errorString)`**  
  Performs an upsert (update or insert) on `LabratoryDetails` via `sp_LabratoryDetailsUpdateInsert`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details. *Note: No `newId` output is provided for this operation.*

- **`ulong LabratoryDetailsGet(IUserDbRecord user, IConnectionDetails connection, string name, out ILabratoryDetailsDbRecord[] labratoryDetailsDbRecords)`**  
  Retrieves `LabratoryDetails` records matching `name` via `sp_LabratoryDetailsGet`. Returns `ERROR_SUCCESS` on success; `labratoryDetailsDbRecords` is an array of valid records, or `null` if none found.

- **`ulong LabratoryDetailsDelete(IUserDbRecord user, IConnectionDetails connection, string name, out string errorString)`**  
  Deletes `LabratoryDetails` records matching `name` via `sp_LabratoryDetailsDelete`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

### `ITestEngineerDetails`

- **`ulong TestEngineerDetailsInsert(IUserDbRecord user, IConnectionDetails connection, TestEngineerDetailsDbRecord testEngineerDetailsDbRecord, out int newId, out string errorString)`**  
  Inserts a new `TestEngineerDetails` record via `sp_TestEngineerDetailsInsert`. Returns `ERROR_SUCCESS` on success; `newId` holds the generated ID. `errorString` may contain SP-level error details.

- **`ulong TestEngineerDetailsUpdate(IUserDbRecord user, IConnectionDetails connection, TestEngineerDetailsDbRecord testEngineerDetailsDbRecord, out string errorString)`**  
  Updates an existing `TestEngineerDetails` record via `sp_TestEngineerDetailsUpdate`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

- **`ulong TestEngineerDetailsUpdateInsert(IUserDbRecord user, IConnectionDetails connection, TestEngineerDetailsDbRecord testEngineerDetailsDbRecord, out string errorString)`**  
  Performs an upsert on `TestEngineerDetails` via `sp_TestEngineerDetailsUpdateInsert`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details. *Note: No `newId` output is provided for this operation.*

- **`ulong TestEngineerDetailsGet(IUserDbRecord user, IConnectionDetails connection, string name, out ITestEngineerDetailsDbRecord[] testEngineerDetailsDbRecords)`**  
  Retrieves `TestEngineerDetails` records matching `name` via `sp_TestEngineerDetailsGet`. Returns `ERROR_SUCCESS` on success; `testEngineerDetailsDbRecords` is an array of valid records, or `null` if none found.

- **`ulong TestEngineerDetailsDelete(IUserDbRecord user, IConnectionDetails connection, string name, out string errorString)`**  
  Deletes `TestEngineerDetails` records matching `name` via `sp_TestEngineerDetailsDelete`. Returns `ERROR_SUCCESS` on success. `errorString` may contain SP-level error details.

## 3. Invariants

- **User Authentication**: All public methods first verify user login via `DbAPI.Connections.IsUserLoggedIn(user, connection)`. If false, they return `ErrorCodes.ERROR_ACCESS_DENIED` without executing any DB operation.
- **Connection Management**: All methods use `ConnectionManager.GetSqlCommand(...)` to obtain a `SqlCommand`. The underlying connection is disposed in `finally` blocks after execution.
- **Error Reporting**:  
  - Return value is a `ulong` error code (0 = `ERROR_SUCCESS`).  
  - SP-level errors are captured via `@errorNumber` (output) and `@errorMessage` (output) parameters.  
  - If SP reports an error (`@errorNumber != 0`), the return value is set to `@errorNumber` (cast to `ulong`).  
  - Exceptions during execution are caught, logged (via `LogManager.Log`), and concatenated into the `errorString` output (format: `"{exception message}; {SP error string}"`).
- **Record Validation**: `Get` methods filter out records where `IsInvalidBlank()` returns `true`.
- **Stored Procedure Naming**: Each operation maps to a specific stored procedure:  
  - Insert → `sp_*Insert`  
  - Update → `sp_*Update`  
  - Upsert → `sp_*UpdateInsert`  
  - Get → `sp_*Get`  
  - Delete → `sp_*Delete`
- **Parameter Consistency**: All insert/update/upsert operations pass the same set of fields (e.g., `@Name`, `@LastModified`, `@Version = 1`) to their respective stored procedures.

## 4. Dependencies

### Module Dependencies (Imports/Usings):
- **Core Infrastructure**:  
  - `DbAPI.Connections` (`IUserDbRecord`, `IConnectionDetails`, `IsUserLoggedIn`, `ConnectionManager`)  
  - `DbAPI.Errors` (`ErrorCodes`, e.g., `ERROR_ACCESS_DENIED`, `ERROR_SUCCESS`, `ERROR_UNKNOWN`)  
  - `DbAPI.Logging` (`LogManager`, `TraceEventType`, `LogEvents.DataRecorders`)  
- **Data Models**:  
  - `DTS.Common.Interface.Database` (`IUserDbRecord`, `IConnectionDetails`)  
  - `DTS.Common.Interface.TestMetaData` (`ICustomerDetailsDbRecord`, `ILabratoryDetailsDbRecord`, `ITestEngineerDetailsDbRecord`)  
  - `DTS.Common.Classes.*` (concrete record types: `CustomerDetailsDbRecord`, `LabratoryDetailsDbRecord`, `TestEngineerDetailsDbRecord`)  
- **System**: `System.Data`, `System.Data.SqlClient`, `System.Diagnostics`, `System.Collections.Generic`

### Module Dependents:
- This module is consumed by higher-level components that require test metadata management (e.g., UI layers, test orchestration services).  
- The interfaces (`ICustomerDetails`, etc.) are likely consumed via dependency injection or factory patterns (not visible in source, but implied by interface design).

## 5. Gotchas

- **Typo in Namespace/Class Names**: The module consistently uses `Labratory` (misspelled) instead of `Laboratory` (e.g., `ILabratoryDetails`, `LabratoryDetailsDbRecord`). This is preserved in the source and must be respected to avoid mismatches with database objects.
- **Inconsistent Parameter Usage in Delete**:  
  - `CustomerDetailsDelete` passes `@Name` with `null` if `name` is empty.  
  - `TestEngineerDetailsDelete` passes `@Name` with `DBNull.Value` if `name` is empty.  
  - `LabratoryDetailsDelete` passes `@LabratoryName` (not `@Name`) with `DBNull.Value` if `name` is empty.  
  This suggests stored procedure parameter names may differ across entities—verify SP signatures.
- **Missing `@LocalOnly` in `TestEngineerDetailsUpdate`**: The `TestEngineerDetailsUpdate` method has a commented-out line for `@LocalOnly`. This may be intentional (e.g., field not updatable) or accidental tech debt.
- **No Upsert Returns New ID**: `UpdateInsert` methods for `LabratoryDetails` and `TestEngineerDetails` do **not** output the new ID (unlike `Insert`), even though the SPs define `@new_id`. This is inconsistent and may require future correction.
- **Error String Handling**: `errorString` is only populated for `Insert`, `Update`, and `Delete` methods when SP reports an error or an exception occurs. `Get` methods do not populate `errorString`—errors are logged and `ERROR_UNKNOWN` is returned.
- **Null/Empty Name Handling**: `Get` and `Delete` methods accept `name` as a filter. `Delete` methods handle empty `name` differently per entity (see above), but `Get` passes `name` directly to the SP (including empty string), which may have unintended behavior if SP does not guard against it.
- **No Concurrency Control**: No versioning or timestamp checks are visible in the client-side code (though `@Version = 1` is passed to SPs). Concurrency handling is entirely delegated to stored procedures.