# Admin Management System

This document describes the admin management system that allows the main admin (superuser) to create and manage other admin users in theRuralPointADVANCE system.

## Features

### 🔐 Access Control
- Only superusers can access admin management features
- Regular admins cannot manage other admins
- Secure authentication and authorization

### 👥 Admin Management
- **Create New Admins**: Add new admin users with different permission levels
- **View Admin List**: See all admin users with filtering and search
- **Edit Admin Details**: Update admin information and permissions
- **Suspend/Reactivate**: Temporarily disable or re-enable admin accounts
- **Audit Trail**: Track all admin management actions

### 🛡️ Permission Levels
- **Superuser**: Full system access, can manage other admins
- **Staff**: Can access Django admin interface
- **Basic Admin**: Standard admin role with limited permissions

## Setup Instructions

### 1. Create a Superuser
First, create a superuser account to access the admin management system:

```bash
python manage.py create_superuser
```

Or use the custom management command:
```bash
python manage.py create_superuser --username admin --email admin@example.com --phone +254700000000 --password admin123
```

### 2. Access Admin Management
1. Log in with your superuser account
2. Navigate to "Admin Management" in the sidebar (only visible to superusers)
3. You'll see the admin management dashboard

## Usage Guide

### Creating a New Admin

1. **Navigate to Admin List**
   - Go to Admin Management → Admin List
   - Click "Add New Admin" button

2. **Fill in Admin Details**
   - **Basic Information**: Name, username, email, phone, status
   - **Authentication**: Password and confirmation
   - **Permissions**: Choose staff access and superuser privileges

3. **Save Admin**
   - Click "Create Admin" to save
   - The new admin will be created with verified email and phone

### Managing Existing Admins

#### View Admin Details
- Click the eye icon (👁️) next to any admin in the list
- View comprehensive information including:
  - Personal details
  - Account status
  - Permissions
  - Recent activity

#### Edit Admin
- Click the edit icon (✏️) next to any admin
- Update information including:
  - Personal details
  - Account status
  - Permissions
  - Password (optional)

#### Suspend Admin
- Click the suspend icon (🚫) next to any admin
- Confirm the action
- Admin will be marked as suspended and cannot log in

#### Reactivate Admin
- For suspended admins, click the reactivate icon (✅)
- Confirm the action
- Admin will be reactivated and can log in again

### Search and Filter

#### Search Admins
- Use the search box to find admins by:
  - Name
  - Username
  - Email
  - Phone number

#### Filter by Status
- Use the status dropdown to filter by:
  - All Status
  - Active
  - Suspended
  - Dormant

## Security Features

### 🔒 Access Control
- Only superusers can access admin management
- Regular admins cannot modify other admin accounts
- Self-deletion prevention (admins cannot delete their own accounts)

### 📝 Audit Logging
- All admin management actions are logged
- Track who performed what action and when
- View audit trail in admin details

### 🛡️ Data Validation
- Email and phone number uniqueness validation
- Password confirmation requirements
- Input sanitization and validation

## URL Structure

```
/users/admins/                    # Admin list
/users/admins/create/             # Create new admin
/users/admins/<uuid>/             # Admin details
/users/admins/<uuid>/edit/        # Edit admin
/users/admins/<uuid>/delete/      # Suspend admin
/users/admins/<uuid>/reactivate/  # Reactivate admin
```

## Django Admin Integration

The system also integrates with Django's built-in admin interface:

- Enhanced user management in Django admin
- Permission-based access control
- Visual indicators for admin roles and permissions
- Only superusers can manage admin users in Django admin

## Troubleshooting

### Common Issues

1. **"Access denied" error**
   - Ensure you're logged in as a superuser
   - Check that your account has `is_superuser=True`

2. **Cannot create admin**
   - Verify email and phone number are unique
   - Ensure password meets requirements
   - Check that you have superuser privileges

3. **Admin cannot log in**
   - Check if admin account is suspended
   - Verify email/phone verification status
   - Ensure account is active

### Getting Help

If you encounter issues:

1. Check the audit logs for error details
2. Verify your superuser permissions
3. Ensure all required fields are filled
4. Check for duplicate email/phone numbers

## Best Practices

### 🔐 Security
- Use strong passwords for admin accounts
- Regularly review admin permissions
- Monitor audit logs for suspicious activity
- Suspend inactive admin accounts

### 👥 Management
- Create admins with minimal required permissions
- Document admin roles and responsibilities
- Regularly review and update admin access
- Use descriptive usernames and emails

### 📊 Monitoring
- Regularly check admin activity logs
- Monitor failed login attempts
- Review admin permissions periodically
- Keep admin contact information updated

## Technical Details

### Models Used
- `CustomUser`: Extended user model with admin-specific fields
- `AuditLog`: Tracks all admin management actions

### Views
- `admin_list`: Display all admin users
- `admin_create`: Create new admin
- `admin_detail`: View admin details
- `admin_update`: Edit admin information
- `admin_delete`: Suspend admin account
- `admin_reactivate`: Reactivate suspended admin

### Templates
- `admin_list.html`: Admin listing with search/filter
- `admin_create.html`: Admin creation form
- `admin_detail.html`: Admin details view
- `admin_update.html`: Admin editing form
- `admin_confirm_delete.html`: Suspension confirmation
- `admin_confirm_reactivate.html`: Reactivation confirmation

### Permissions
- `is_superuser`: Required for all admin management
- `is_staff`: Access to Django admin interface
- `role='admin'`: Admin role designation
- `status`: Account status (active, suspended, dormant)