# Super Admin Management System Documentation

## Overview

Super admins can now fully manage other admin accounts including creating, editing, suspending, and deleting admin users. The system includes comprehensive role-based access control, activity logging, and a complete web interface for admin management.

---

## Features Implemented

✅ **Admin Account Management**
- Create new admin accounts with custom roles
- Edit existing admin account details
- Update admin roles and permissions
- Change admin passwords
- Suspend/activate admin accounts
- Delete admin accounts with confirmation

✅ **Role-Based Access Control**
- 5 different admin roles with distinct permissions
- Role hierarchy system (super_admin cannot be managed by lower roles)
- Module-level access control
- Granular permission system (49 permissions)

✅ **Activity Logging**
- All admin management actions logged
- Deletion reason tracking for audit compliance
- Last login tracking
- IP address logging

✅ **Security Features**
- Email confirmation for deletions
- Deletion reason requirement
- Status management (active/suspended)
- Password management
- Super admin protection

---

## Routes & URLs

### Admin Management Routes (Protected - Super Admin Only)

```
GET    /admin/admins                          → List all admins
GET    /admin/admins/create                   → Create admin form
POST   /admin/admins                          → Store new admin
GET    /admin/admins/{admin}                  → View admin details
GET    /admin/admins/{admin}/edit             → Edit admin form
PATCH  /admin/admins/{admin}                  → Update admin
GET    /admin/admins/{admin}/confirm-delete   → Delete confirmation
DELETE /admin/admins/{admin}                  → Delete admin
PATCH  /admin/admins/{admin}/toggle-status    → Suspend/activate admin
GET    /admin/admins/{admin}/verify-permissions → JSON verification
```

### Access Requirements
- **Route Middleware:** `admin.role:super_admin`
- **Permission Checks:**
  - `manage_admins` - View and manage admins
  - `create_admin` - Create new admin accounts
  - `edit_admin` - Edit existing admin accounts
  - `delete_admin` - Delete admin accounts
  - `view_admin_logs` - Verify permissions endpoint

---

## Controller: AdminManagementController

**File:** `app/Http/Controllers/Admin/AdminManagementController.php`

### Methods

#### `index()`
- **Permission:** `manage_admins`
- **Purpose:** List all admin accounts with pagination
- **Returns:** `admin.admins.index` view with paginated admins

#### `create()`
- **Permission:** `create_admin`
- **Purpose:** Show form for creating new admin
- **Returns:** `admin.admins.create` view with roles configuration

#### `store(Request $request)`
- **Permission:** `create_admin`
- **Validation:**
  - `name` (required, string, max 255)
  - `email` (required, email, unique)
  - `password` (required, min 8, confirmed)
  - `role` (required, in valid roles enum)
  - `status` (required, in: active, inactive, suspended)
  - `phone` (nullable, max 20)
- **Creates:** Admin record + logs activity
- **Returns:** Redirect to show with success message

#### `show(Admin $admin)`
- **Permission:** `manage_admins`
- **Purpose:** Display detailed admin information
- **Shows:** Permissions, modules, activity, dates
- **Returns:** `admin.admins.show` view

#### `edit(Admin $admin)`
- **Permission:** `edit_admin`
- **Hierarchy Check:** Verifies admin can manage target admin
- **Returns:** `admin.admins.edit` view with pre-filled form

#### `update(Request $request, Admin $admin)`
- **Permission:** `edit_admin`
- **Hierarchy Check:** Verifies admin can manage target admin
- **Validation:** Name, email, role, status, phone, optional password
- **Features:**
  - Optional password change
  - Role change tracking
  - Status change logging
- **Logs:** Changes made for audit trail

#### `confirmDelete(Admin $admin)`
- **Permission:** `delete_admin`
- **Purpose:** Show deletion confirmation form
- **Returns:** `admin.admins.confirm-delete` view

#### `destroy(Request $request, Admin $admin)`
- **Permission:** `delete_admin`
- **Hierarchy Check:** Verifies admin can manage target admin
- **Requires:**
  - Email confirmation (must match exactly)
  - Deletion reason
- **Actions:**
  - Soft deletes admin record
  - Logs deletion with reason
  - Marks deletion for audit
- **Returns:** Redirect to index with success message

#### `toggleStatus(Request $request, Admin $admin)`
- **Permission:** `manage_admins`
- **Purpose:** Suspend or activate admin account
- **Features:**
  - Toggles between active/suspended
  - Logs status changes
- **Returns:** Redirect back with status message

#### `verifyPermissions(Admin $admin)`
- **Permission:** `view_admin_logs`
- **Purpose:** JSON endpoint for permission verification
- **Returns:** JSON with admin permissions and modules

---

## Views & Blade Templates

### 1. **index.blade.php** - Admin List
**File:** `resources/views/admin/admins/index.blade.php`

Features:
- Paginated list of all admins (15 per page)
- Role badges with color coding
- Status indicators
- Quick actions: View, Edit, Suspend, Delete
- Responsive table layout

### 2. **create.blade.php** - Create Admin Form
**File:** `resources/views/admin/admins/create.blade.php`

Fields:
- Full Name (required)
- Email Address (required, unique)
- Phone Number (optional)
- Admin Role (required, with descriptions)
- Status (required, default: active)
- Password (required, min 8 characters)
- Confirm Password

Features:
- Dynamic role information display
- Live role description updates
- Role capabilities list
- Form validation feedback

### 3. **edit.blade.php** - Edit Admin Form
**File:** `resources/views/admin/admins/edit.blade.php`

Features:
- Pre-filled form with current values
- Optional password change section
- Admin information sidebar (created date, last login)
- Permission and module summary
- Status change tracking

### 4. **show.blade.php** - Admin Details
**File:** `resources/views/admin/admins/show.blade.php`

Sections:
- Account Information
- Status management
- Role & Permissions display
- Accessible Modules list
- Detailed permissions grid
- Login activity tracking
- Account dates (created, updated, deleted)
- Quick action buttons (Edit, Delete)

### 5. **confirm-delete.blade.php** - Delete Confirmation
**File:** `resources/views/admin/admins/confirm-delete.blade.php`

Safety Features:
- Email address confirmation field
- Deletion reason text area
- Understanding acknowledgment checkbox
- Delete button disabled until confirmation
- Information about consequences
- What happens on deletion details

---

## Admin Model Enhanced

**File:** `app/Models/Admin.php`

New Methods Added:
- `getPermissions()` - Get all permissions for role
- `getAccessibleModules()` - Get all modules for role
- `hasPermission($permission)` - Check specific permission
- `hasAnyPermission($permissions)` - Check any permission in array
- `hasAllPermissions($permissions)` - Check all permissions required
- `hasModuleAccess($module)` - Check module access
- `canManage($resource)` - Check resource management
- `canManageAdmin($admin)` - Check admin hierarchy
- `getRoleDetails()` - Get role configuration
- `getDashboardConfig()` - Get dashboard configuration

---

## Authorization Trait

**File:** `app/Traits/AdminAuthorization.php`

Methods for use in controllers:
- `authorizePermission($permission)` - Throws 403 if no permission
- `authorizeRole(...$roles)` - Throws 403 if wrong role
- `canManageAdmin($targetAdmin)` - Check hierarchy
- `authorizeAdminManagement($targetAdmin)` - Authorize management
- `admin()` - Get current admin
- `hasPermission($permission)` - Check permission
- `hasAnyPermission($permissions)` - Check any permission
- `hasModuleAccess($module)` - Check module access

---

## Activity Logging

All admin management actions are logged via `AdminActivityLog`:

```php
AdminActivityLog::log(
    'admin.created',
    "Admin {$admin->name} ({$admin->email}) was created",
    'Admin',
    auth('admin')->id()
);
```

Logged Events:
- `admin.created` - New admin account created
- `admin.updated` - Admin details updated
- `admin.deleted` - Admin account deleted
- `admin.status_changed` - Admin status changed

---

## Database Schema

### Admins Table

```php
$table->id();
$table->string('name');
$table->string('email')->unique();
$table->timestamp('email_verified_at')->nullable();
$table->string('password');
$table->enum('role', [
    'super_admin',
    'operations_admin',
    'moderator',
    'employer_manager',
    'finance_admin'
])->default('moderator');
$table->enum('status', [
    'active',
    'inactive',
    'suspended'
])->default('active');
$table->string('avatar')->nullable();
$table->string('phone')->nullable();
$table->boolean('two_factor_enabled')->default(false);
$table->text('two_factor_secret')->nullable();
$table->rememberToken();
$table->timestamp('last_login_at')->nullable();
$table->string('last_login_ip')->nullable();
$table->timestamps();
$table->softDeletes();
```

---

## Usage Examples

### In Controller

```php
use App\Traits\AdminAuthorization;

class AdminManagementController extends Controller
{
    use AdminAuthorization;
    
    public function store(Request $request)
    {
        $this->authorizePermission('create_admin');
        
        $admin = Admin::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => Hash::make($request->password),
            'role' => $request->role,
        ]);
        
        return redirect()->route('admin.admins.show', $admin);
    }
}
```

### In Blade View

```blade
@if(auth('admin')->user()->hasPermission('manage_admins'))
    <a href="{{ route('admin.admins.index') }}">Manage Admins</a>
@endif

@if(admin_permission('create_admin'))
    <a href="{{ route('admin.admins.create') }}">Create Admin</a>
@endif
```

### Checking Role Hierarchy

```php
$admin = auth('admin')->user();

// Check if can manage another admin
if ($admin->canManageAdmin($targetAdmin)) {
    // Can manage this admin
}

// Only super admin can manage operations admin
$superAdmin->canManageAdmin($opsAdmin); // true
$opsAdmin->canManageAdmin($superAdmin); // false
```

---

## Role Hierarchy

The system implements a strict role hierarchy:

```
Super Admin (5)
    ├─ Can manage: All roles
    └─ Full system control

Operations Admin (4)
    ├─ Can manage: Moderator, Employer Manager, Finance Admin
    └─ Operational control

Finance Admin (3)
    ├─ Can manage: None
    └─ Financial operations only

Employer Manager (2)
    ├─ Can manage: None
    └─ Employer account management

Moderator (1)
    ├─ Can manage: None
    └─ Content moderation only
```

---

## Validation Rules

### Create/Update Admin

```php
[
    'name' => ['required', 'string', 'max:255'],
    'email' => ['required', 'email', 'unique:admins,email'],
    'password' => ['required', 'string', 'min:8', 'confirmed'],
    'role' => ['required', 'string', 'in:super_admin,operations_admin,moderator,employer_manager,finance_admin'],
    'status' => ['required', 'string', 'in:active,inactive,suspended'],
    'phone' => ['nullable', 'string', 'max:20'],
]
```

### Delete Admin

```php
[
    'confirm_email' => ['required', 'email'],
    'reason' => ['required', 'string', 'max:500'],
]
```

---

## Error Handling

The system includes comprehensive error handling:

- **Permission Denied** → 403 Forbidden status
- **Unauthorized Role** → 403 Forbidden status
- **Validation Errors** → Redirect back with errors
- **Database Errors** → Error message displayed
- **Email Conflicts** → Validation error message
- **Role Violations** → Authorization exception

---

## Security Considerations

1. ✅ **Super Admin Protection** - Only super admins can manage other admins
2. ✅ **Role Hierarchy** - Lower-level admins cannot manage higher-level admins
3. ✅ **Deletion Confirmation** - Email confirmation required
4. ✅ **Reason Tracking** - Deletion reasons logged for audit
5. ✅ **Permission Validation** - All actions checked server-side
6. ✅ **Activity Logging** - All changes logged with admin ID
7. ✅ **Soft Deletes** - Admin records preserved for audit
8. ✅ **Status Management** - Can suspend instead of delete

---

## Testing the System

### Login as Super Admin
```
URL: http://127.0.0.1:8000/admin/login
Email: admin@cura.test
Password: Admin@123456
```

### Test Workflows

1. **Create Admin**
   - Navigate to /admin/admins
   - Click "Create Admin"
   - Fill form with role selection
   - Submit and verify creation

2. **Edit Admin**
   - Go to admin list
   - Click "Edit" on any admin
   - Change details/password
   - Update and verify changes logged

3. **Suspend Admin**
   - View admin details
   - Click "Suspend Account"
   - Verify status changes

4. **Delete Admin**
   - Navigate to delete confirmation
   - Enter email address
   - Enter deletion reason
   - Confirm and delete

---

## Advanced Features

### Permission Verification Endpoint

```
GET /admin/admins/{admin}/verify-permissions
```

Returns JSON with admin's complete permission set:

```json
{
    "admin": {
        "id": 1,
        "name": "Admin User",
        "email": "admin@cura.test",
        "role": "super_admin",
        "status": "active"
    },
    "permissions_count": 49,
    "modules_count": 11,
    "permissions": ["manage_admins", "create_admin", ...],
    "modules": ["admin_management", "system_settings", ...]
}
```

### Dashboard Widget Configuration

Based on role, different dashboard widgets are displayed:

```php
'super_admin' => [
    'system_overview',
    'user_statistics',
    'recent_activity',
    'system_health',
    'user_growth',
    'financial_summary',
],
```

---

## Troubleshooting

### Super Admin Can't Create Admin?
- Verify super admin has `create_admin` permission
- Check middleware is `admin.role:super_admin`
- Verify admin is active in database

### Edit Form Shows Wrong Info?
- Clear browser cache
- Verify form pre-filling with old() helper
- Check database for current values

### Deletion Not Working?
- Email confirmation must match exactly
- Ensure deletion reason is provided
- Verify checkbox is checked
- Check user has `delete_admin` permission

### Activity Not Logging?
- Verify AdminActivityLog model exists
- Check auth('admin')->id() returns value
- Verify database connection

---

## Related Files

- **Controller:** `app/Http/Controllers/Admin/AdminManagementController.php`
- **Routes:** `routes/admin.php` (lines ~170-185)
- **Views:** `resources/views/admin/admins/`
  - `index.blade.php`
  - `create.blade.php`
  - `edit.blade.php`
  - `show.blade.php`
  - `confirm-delete.blade.php`
- **Model:** `app/Models/Admin.php`
- **Trait:** `app/Traits/AdminAuthorization.php`
- **Config:** `config/admin_permissions.php`
- **Service:** `app/Services/AdminPermissionService.php`