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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T04:25:29.306320+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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.