--- 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.