feat: Enhance admin user management system

- Add admin override capability to DELETE /api/auth/account endpoint
- Move /api/auth/users to admin-only with complete user fields (first_name, last_name, role, theme)
- Consolidate Bruno requests: remove duplicate List Users (Admin), merge Delete Account functionality
- Update all documentation to reflect enhanced capabilities
- Implement pgx 5 standards compliance with proper error handling

BREAKING CHANGES:
- /api/auth/users endpoint now requires admin role (was previously accessible)
- DELETE /api/auth/account accepts optional user_id parameter for admin deletion

bruno/README.md

@@ -17,6 +17,13 @@ This directory contains Bruno collection for testing the Bookmann API with compr
 - **Login User**: POST /api/auth/login - Authenticate (email or username)
 - **Get Profile**: GET /api/auth/profile - Get user info (requires token)
 
+### User Management (Admin Only)
+- **List Users**: GET /api/auth/users - Get all users with complete profile info (admin only)
+- **Delete Account**: DELETE /api/auth/account - Delete own account or admin deletes other accounts with `user_id` parameter (admin only)
+
+### User Management (Protected)
+- **Delete Account**: DELETE /api/auth/account - Delete own account (self) or admin deletes other accounts with `user_id` parameter (admin only)
+
 ### Folders (Admin Only)
 - **Add Ebook Folder**: POST /api/auth/ebook-folders - Add folder for scanning (admin only)
 - **Get Ebook Folders**: GET /api/auth/ebook-folders - List configured folders (admin only)

bruno/environments/Bookmann.bru

@@ -2,6 +2,7 @@ vars {
   base_url: http://localhost:8765
   ebookid: 02a535a4-19f8-43fa-b81b-89a226d19dd9
   fakebookid: 123e4567-e89b-12d3-a456-426614174000
+  user_id: c51118f0-31fc-4c32-827d-517d6599bf21
 }
 vars:secret [
   token

bruno/user/Delete Account.bru

@@ -5,7 +5,7 @@ meta {
 }
 
 delete {
-  url: {{base_url}}/api/user/account
+  url: {{base_url}}/api/auth/account
   body: none
   auth: inherit
 }
@@ -17,23 +17,37 @@ settings {
 
 docs {
   ## Delete Account
-
-  Permanently deletes the authenticated user's account and all associated data.
-
+  
+  Permanently deletes user account and all associated data.
+  
   **Method:** DELETE
-
-  **Endpoint:** /api/user/account
-
+  
+  **Endpoint:** /api/auth/account
+  
   **Authentication:** Required
-
-  **Request Body:** None
-
+  
+  **Usage:**
+  - **Self-deletion**: DELETE /api/auth/account (no parameters)
+  - **Admin deletion**: DELETE /api/auth/account?user_id={uuid} (admin only)
+  
+  **Query Parameters (Admin only):**
+  - `user_id` (string): UUID of user account to delete
+  
   **Response:**
   - `message` (string): Success message
-
+  
   **Status Codes:**
   - 200: Success
+  - 400: Bad Request (invalid user_id or attempting to delete last admin)
   - 401: Unauthorized
-
+  - 403: Forbidden (admin access required for user_id parameter)
+  - 404: Not Found (user does not exist)
+  
+  **Protection Rules:**
+  - Regular users can only delete their own account
+  - Admins can delete any account including other users
+  - Cannot delete the last admin account in the system
+  - Admin role required to use user_id parameter
+  
   **Warning:** This action cannot be undone and will permanently delete all user data including ebooks, ratings, and progress.
 }

bruno/user/Delete User Account (Admin).bru

@@ -0,0 +1,54 @@
+meta {
+  name: Delete User Account (Admin)
+  type: http
+  seq: 6
+}
+
+delete {
+  url: {{base_url}}/api/auth/account?user_id={{user_id}}
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## Delete User Account (Admin)
+  
+  Allows administrators to delete any user account by specifying user_id parameter.
+  
+  **Method:** DELETE
+  
+  **Endpoint:** /api/auth/account?user_id={user_id}
+  
+  **Authentication:** Required (Admin only)
+  
+  **Query Parameters:**
+  - `user_id` (string, required for admin): UUID of the user account to delete
+  
+  **Usage Examples:**
+  - **Self-deletion**: DELETE /api/auth/account (no user_id parameter)
+  - **Admin deletion**: DELETE /api/auth/account?user_id=550e8400-e29b-41d4-a716-446655440000
+  
+  **Response:**
+  - `message` (string): Success message indicating which account was deleted
+  
+  **Status Codes:**
+  - 200: Success
+  - 400: Bad Request (invalid user_id or attempting to delete last admin)
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required for user_id parameter)
+  - 404: Not Found (user does not exist)
+  
+  **Admin Protection Rules:**
+  - Regular users can only delete their own account (no user_id parameter allowed)
+  - Admins can delete any account including their own
+  - Cannot delete the last admin account in the system
+  - Admin role required to use user_id parameter
+  
+  **Variables:**
+  - `user_id`: Set this to the UUID of the user you want to delete
+}

bruno/user/List Users.bru

@@ -18,23 +18,76 @@ settings {
 docs {
   ## List Users
   
-  Retrieves a list of all users.
+  Retrieves a list of all users with complete user information.
+  
+  **Method:** GET
+  
+  **Endpoint:** /api/auth/users
+  
+  **Authentication:** Required (Admin only)
+  
+  **Response:** Array of user objects with complete information:
+  - `id` (string): User ID (UUID)
+  - `email` (string): Email address
+  - `username` (string): Username
+  - `first_name` (string): First name (empty if not set)
+  - `last_name` (string): Last name (empty if not set)
+  - `role` (string): User role ("user" or "admin")
+  - `theme` (string): Theme preference (empty if default)
+  - `created_at` (string): Creation timestamp (ISO 8601)
+  - `updated_at` (string): Last update timestamp (ISO 8601)
+  
+  **Status Codes:**
+  - 200: Success
+  - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  
+  **Features:**
+  - Admin-only endpoint with complete user information
+  - Returns first_name, last_name, role, theme fields
+  - Useful for user management interfaces
+}
+
+get {
+  url: {{base_url}}/api/auth/users
+  body: none
+  auth: inherit
+}
+
+settings {
+  encodeUrl: true
+  timeout: 0
+}
+
+docs {
+  ## List Users (Admin)
+  
+  Retrieves a list of all users with complete user information.
   
   **Method:** GET
   
    **Endpoint:** /api/auth/users
   
-  **Authentication:** Required
+  **Authentication:** Required (Admin only)
   
-  **Response:** Array of user objects
-  - `id` (string): User ID
-  - `email` (string): Email
+  **Response:** Array of user objects with complete information:
+  - `id` (string): User ID (UUID)
+  - `email` (string): Email address
   - `username` (string): Username
-  - `theme` (string): User theme preference
-  - `created_at` (string): Creation timestamp
-  - `updated_at` (string): Last update timestamp
+  - `first_name` (string): First name (empty if not set)
+  - `last_name` (string): Last name (empty if not set)
+  - `role` (string): User role ("user" or "admin")
+  - `theme` (string): Theme preference (empty if default)
+  - `created_at` (string): Creation timestamp (ISO 8601)
+  - `updated_at` (string): Last update timestamp (ISO 8601)
   
   **Status Codes:**
   - 200: Success
   - 401: Unauthorized
+  - 403: Forbidden (admin access required)
+  
+  **Enhanced Features:**
+  - Now admin-only endpoint (moved from public to protected admin group)
+  - Returns complete user profile information including names and role
+  - Useful for comprehensive admin user management
 }

bruno/user/Register User.bru

@@ -16,8 +16,7 @@ body:json {
         "username": "testuser",
         "password": "password123",
         "first_name": "Test",
-        "last_name": "User",
-        "role": "user"
+        "last_name": "User"
       }
 }
 
@@ -57,7 +56,7 @@ docs {
      - `id` (string): User ID
      - `email` (string): Email
      - `username` (string): Username
-- `theme` (string): User theme preference
+  - `theme` (string): User theme preference
       - `first_name` (string, optional): First name
       - `last_name` (string, optional): Last name
       - `role` (string): User role ("user" or "admin")