92 lines
5.7 KiB
Markdown
92 lines
5.7 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/DbAPI/Groups/IGroupHardware.cs
|
|
- DataPRO/DbAPI/Groups/IGroups.cs
|
|
- DataPRO/DbAPI/Groups/GroupHardware.cs
|
|
- DataPRO/DbAPI/Groups/Groups.cs
|
|
generated_at: "2026-04-17T15:53:56.485523+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "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 |