# Client Approval System - Deployment Guide

## Overview
This guide covers the deployment of the Client Approval System to production. The system adds an approval workflow for new client registrations.

## What's Included

### Files Modified/Created
1. **users/migrations/0023_customuser_approval_reason_customuser_approved_at_and_more.py**
   - Adds approval and rejection fields to the CustomUser model
   - Fields: `approved_by`, `approved_at`, `approval_reason`, `rejected_by`, `rejected_at`, `rejection_reason`

2. **users/views.py**
   - `pending_clients()` - List pending clients
   - `approve_client()` - Approve a client
   - `reject_client()` - Reject a client
   - `bulk_approve_clients()` - Bulk approve clients

3. **users/urls.py**
   - Routes for approval functionality

4. **templates/users/pending_clients.html**
   - Template for managing pending approvals

5. **templates/users/client_list.html**
   - Added "Pending Approvals" button for admins

6. **templates/base.html**
   - Updated navigation (removed submenu, back to simple Clients link)

## Database Migration

The migration adds the following fields to the `users` table:

```sql
- approved_by_id (INT, Foreign Key to users table)
- approved_at (DATETIME, NULL)
- approval_reason (TEXT, NULL)
- rejected_by_id (INT, Foreign Key to users table)
- rejected_at (DATETIME, NULL)
- rejection_reason (TEXT, NULL)
```

## Deployment Methods

### Method 1: Python Script (Recommended)

```bash
python deploy_client_approval_system.py
```

This script will:
1. Check database connection
2. Verify current database structure
3. Run migrations
4. Verify migration success
5. Test the approval system

### Method 2: Shell Script

```bash
chmod +x deploy_client_approval_system.sh
./deploy_client_approval_system.sh
```

### Method 3: Manual Deployment

```bash
# 1. Backup your database
mysqldump -u username -p database_name > backup_before_approval.sql

# 2. Run migrations
python manage.py migrate users

# 3. Verify
python manage.py check
```

## Pre-Deployment Checklist

- [ ] Backup the production database
- [ ] Test in staging environment first
- [ ] Ensure all Django migrations are up to date
- [ ] Verify database credentials are correct
- [ ] Check that `CustomUser` model is accessible
- [ ] Verify admin users exist

## Post-Deployment Checklist

- [ ] Test the Client List page loads
- [ ] Verify "Pending Approvals" button appears for admins
- [ ] Test creating a new client (should be in pending_approval status)
- [ ] Test approving a pending client
- [ ] Test rejecting a pending client (with reason)
- [ ] Check audit logs for approval/rejection actions
- [ ] Verify notifications are sent to clients
- [ ] Test bulk approval functionality

## Accessing the Feature

### For Administrators

1. Navigate to **Clients** from the sidebar
2. Click the **"Pending Approvals"** button (yellow button with clock icon)
3. Review pending clients
4. Approve or reject clients individually or in bulk

### Client Status Flow

```
New Registration → pending_approval → active (approved)
                                ↓
                          inactive (rejected)
```

## Troubleshooting

### Issue: "Unknown column 'users.approved_by_id' in 'field list'"

**Solution**: The migration hasn't been applied. Run:
```bash
python manage.py migrate users
```

### Issue: Pending Approvals button not showing

**Solution**: 
1. Verify the user has admin role
2. Check browser cache
3. Verify template changes are deployed

### Issue: Cannot approve clients

**Solution**:
1. Verify you're logged in as admin
2. Check if client is in `pending_approval` status
3. Check Django logs for errors

### Issue: Notifications not sending

**Solution**:
1. Check notification settings
2. Verify Notification model exists
3. Check email/SMS configuration if applicable

## Rollback

If you need to rollback the approval system:

```bash
# Rollback the migration
python manage.py migrate users 0022_remove_rolepermission_role_permis_role_056d99_idx_and_more

# Or manually remove the columns (careful - data loss!)
```

## Testing

### Test Cases

1. **Create Client Test**
   - Create a new client
   - Verify status is `pending_approval`
   - Check user cannot login yet

2. **Approve Client Test**
   - Approve a pending client
   - Verify status changes to `active`
   - Check audit log created
   - Verify notification sent

3. **Reject Client Test**
   - Reject a pending client with reason
   - Verify status changes to `inactive`
   - Check audit log created
   - Verify notification sent with reason

4. **Bulk Approve Test**
   - Select multiple pending clients
   - Bulk approve them
   - Verify all are approved
   - Check audit logs

5. **Permission Test**
   - Non-admin user tries to access pending approvals
   - Should be blocked or redirected

## Support

For issues or questions:
1. Check the application logs
2. Review Django debug output
3. Check database for migration status
4. Verify permissions and user roles

## Feature Summary

- ✅ Pending clients list with search
- ✅ Individual approve/reject actions
- ✅ Bulk approve functionality
- ✅ Rejection reason required
- ✅ Approval notes optional
- ✅ Audit logging for all actions
- ✅ Client notifications
- ✅ Admin-only access
- ✅ Branch filtering support