DP44/docs/ai/DataPRO/DbAPI/Groups.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/DbAPI/Groups/IGroupHardware.cs DataPRO/DbAPI/Groups/IGroups.cs DataPRO/DbAPI/Groups/GroupHardware.cs DataPRO/DbAPI/Groups/Groups.cs	2026-04-17T15:53:56.485523+00:00	zai-org/GLM-5-FP8	1	c8fc5d8b5716c64f

Documentation: DbAPI.Groups Module

1. Purpose

This module provides the database access layer for managing Groups and GroupHardware entities in the DataPRO system. It implements CRUD operations (Create, Read, Update, Delete) for both the Groups and GroupHardware database tables via stored procedure calls. The module enforces user authentication before any database operation and provides standardized error handling with logging. It serves as the data persistence layer for group-related functionality, bridging higher-level business logic with the underlying SQL database.

---

2. Public Interface

Interface: IGroupHardware

Defines operations for the GroupHardware junction table (associating hardware devices with groups).

Method	Signature	Description
GroupHardwareInsert	ulong GroupHardwareInsert(IUserDbRecord user, IConnectionDetails connection, GroupHardwareDbRecord groupHardware, out int newId, out string errorMessage)	Inserts a new record into the GroupHardware table. Returns ERROR_SUCCESS (0) on success; newId receives the generated ID.
GroupHardwareGet	ulong GroupHardwareGet(IUserDbRecord user, IConnectionDetails connection, int? groupId, string serialNumber, bool? embedded, out GroupHardwareDbRecord[] groupHardwareRecords)	Retrieves one or more records from GroupHardware table. Supports filtering by groupId, serialNumber, and embedded flags.
GroupHardwareDelete	ulong GroupHardwareDelete(IUserDbRecord user, IConnectionDetails connection, int? groupId, int? dasId, out string errorString)	Deletes an entry from GroupHardware table. Can filter by groupId and/or dasId.

Interface: IGroups

Defines operations for the Groups table (group definitions).

Method	Signature	Description
GroupsInsert	ulong GroupsInsert(IUserDbRecord user, IConnectionDetails connection, ref IGroupDbRecord group)	Inserts a new record into Groups table. The group parameter is passed by ref and its Id property is populated with the new ID on success.
GroupsUpdate	ulong GroupsUpdate(IUserDbRecord user, IConnectionDetails connection, IGroupDbRecord group)	Updates an existing record in Groups table. Uses group.Id to identify the record to update.
GroupsGet	ulong GroupsGet(IUserDbRecord user, IConnectionDetails connection, int? id, string serialNumber, string displayName, bool? embedded, int? staticGroupId, out IGroupDbRecord[] groups)	Retrieves one or more records from Groups table. Supports filtering by id, serialNumber, displayName, embedded, and staticGroupId.
GroupsDelete	ulong GroupsDelete(IUserDbRecord user, IConnectionDetails connection, long id, out string errorString)	Deletes a record from Groups table by id.

Return Values

All methods return ulong error codes:

• 0 = ERROR_SUCCESS (operation succeeded)
• ERROR_ACCESS_DENIED = user authentication failed
• ERROR_UNKNOWN = unexpected exception occurred
• Other values = stored procedure-specific error codes

---

3. Invariants

1. Authentication Required: Every public method checks DbAPI.Connections.IsUserLoggedIn(user, connection) before proceeding. If this returns false, the method immediately returns ERROR_ACCESS_DENIED.

2. Return Code Semantics: A return value of 0 (ERROR_SUCCESS) always indicates success. All non-zero values indicate failure.

3. Stored Procedure Usage: All database operations are performed exclusively through stored procedures:

   • sp_GroupHardwareInsert, sp_GroupHardwareGet, sp_GroupHardwareDelete
   • sp_GroupsInsert, sp_GroupsUpdate, sp_GroupsGet, sp_GroupsDelete

4. Connection Cleanup: All methods dispose of the SqlCommand.Connection in a finally block, ensuring connections are released even on exceptions.

5. Output Parameter Pattern: Insert stored procedures return the new ID via an output parameter (@new_id). Delete and some other procedures return error information via @errorNumber and @errorMessage output parameters.

6. Nullable Filter Parameters: All filter parameters in Get methods are nullable, allowing flexible querying (e.g., query by groupId only, or combine multiple filters).

---

4. Dependencies

This Module Depends On:

Dependency	Usage
DbAPI.Connections	ConnectionManager.GetSqlCommand(), IsUserLoggedIn()
DbAPI.Errors	ErrorCodes constants (ERROR_SUCCESS, ERROR_ACCESS_DENIED, ERROR_UNKNOWN)
DbAPI.Logging	LogManager.Log() for error logging
DTS.Common.Interface.Database	IUserDbRecord interface
DTS.Common.Interface.Groups	IGroupDbRecord interface
DTS.Common.Classes.Groups	GroupHardwareDbRecord, GroupDbRecord concrete classes
System.Data.SqlClient	ADO.NET SQL Server client (SqlCommand, SqlParameter, SqlDataReader)

Consumers (Inferred):

• Any module that registers or resolves IGroupHardware or IGroups via dependency injection
• Higher-level business logic layers that need to persist or retrieve group data

---

5. Gotchas

1. Inconsistent Error Code Handling in GroupHardwareDelete: When the stored procedure returns a non-zero error number, the method throws an exception and returns ERROR_UNKNOWN instead of returning the actual error code from the procedure. This differs from GroupsDelete, which correctly returns the stored procedure's error code.

2. **Misleading Log