HH/docs/SLA_TESTING_GUIDE.md

# SLA Testing Guide

This guide provides comprehensive information for testing the Service Level Agreement (SLA) system, including the new second reminder feature.

## Overview

The SLA system ensures complaints are resolved within specified timeframes by:
- **First Reminder**: Sent at a configurable time before the complaint is due
- **Second Reminder** (NEW): Sent closer to the due date if no action has been taken
- **Escalation**: Automatically escalates complaints if they remain overdue
- **Thank You Email**: Sent when a complaint is closed

## System Components

### 1. Complaint Model (`apps/complaints/models.py`)

Key SLA-related fields:
- `due_at`: When the complaint is due
- `reminder_sent_at`: Timestamp when first reminder was sent
- `second_reminder_sent_at`: Timestamp when second reminder was sent (NEW)
- `is_overdue`: Boolean flag for overdue status
- `escalated_at`: Timestamp when escalation occurred
- `metadata`: JSON field storing escalation history

### 2. SLA Configuration (`ComplaintSLAConfig`)

Configurable per hospital, severity, and priority:
- `sla_hours`: Total SLA duration (e.g., 48 hours)
- `reminder_hours_before`: First reminder timing (e.g., 24 hours before due)
- `second_reminder_enabled`: Enable/disable second reminder (NEW)
- `second_reminder_hours_before`: Second reminder timing (e.g., 6 hours before due)
- `thank_you_email_enabled`: Enable thank you email on close

### 3. Escalation Rules (`EscalationRule`)

Multi-level escalation logic:
- **Level 1**: Department Manager (triggers when overdue)
- **Level 2**: Hospital Admin (triggers after first reminder + X hours)
- **Level 3+**: Configurable higher-level roles

### 4. Celery Tasks (`apps/complaints/tasks.py`)

- `send_sla_reminders()`: Runs hourly to check and send reminders
- `check_overdue_complaints()`: Runs hourly to flag overdue complaints
- `escalate_after_reminder()`: Runs after reminders to escalate if needed

## Email Templates

### First Reminder
- English: `templates/complaints/emails/sla_reminder_en.txt`
- Arabic: `templates/complaints/emails/sla_reminder_ar.txt`

### Second Reminder (NEW)
- English: `templates/complaints/emails/sla_second_reminder_en.txt`
- Arabic: `templates/complaints/emails/sla_second_reminder_ar.txt`

## Automated Testing

### Run the Test Suite

```bash
# Run the comprehensive SLA test script
python test_sla_functionality.py
```

The test script:
1. Creates test hospital, department, user, and staff
2. Sets up SLA configuration with second reminder enabled
3. Creates escalation rules
4. Generates a test complaint with specific timing
5. Tests first reminder logic
6. Tests second reminder logic
7. Tests escalation logic
8. Displays complaint timeline

### Test Output Analysis

The test output shows:
- ✓ Test data setup status
- ✓ SLA configuration details
- ✓ Escalation rules configured
- ✓ Complaint creation details
- Reminder timing calculations
- Current escalation status
- Timeline updates

## Manual Testing

### 1. Configure SLA Settings

**Via Admin Panel:**
1. Login as admin
2. Navigate to: `/admin/complaints/complaintslaconfig/add/`
3. Configure for your hospital:
   ```
   Hospital: Your Hospital
   Severity: medium
   Priority: medium
   SLA Hours: 48
   Reminder Hours Before: 24
   Second Reminder Enabled: ✓
   Second Reminder Hours Before: 6
   Thank You Email Enabled: ✓
   Is Active: ✓
   ```
4. Save

**Via API:**
```bash
curl -X POST http://localhost:8000/api/complaints/sla-configs/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "hospital": "HOSPITAL_UUID",
    "severity": "medium",
    "priority": "medium",
    "sla_hours": 48,
    "reminder_hours_before": 24,
    "second_reminder_enabled": true,
    "second_reminder_hours_before": 6,
    "thank_you_email_enabled": true
  }'
```

### 2. Create Test Complaint

Create a complaint with specific timing to test reminders:

```python
from datetime import timedelta
from django.utils import timezone
from apps.complaints.models import Complaint, ComplaintStatus

# Due in 26 hours (triggers first reminder at 24h, second at 6h)
complaint = Complaint.objects.create(
    title="SLA Test Complaint",
    description="Testing SLA reminders",
    hospital=hospital,
    department=department,
    status=ComplaintStatus.OPEN,
    priority='medium',
    severity='medium',
    due_at=timezone.now() + timedelta(hours=26),
    is_overdue=False
)
```

### 3. Trigger Reminders Manually

```bash
# Trigger reminder task
celery -A config worker -l info
celery -A config beat -l info

# Or trigger manually from Django shell
python manage.py shell

>>> from apps.complaints.tasks import send_sla_reminders
>>> result = send_sla_reminders.delay()
>>> print(result.get())
```

### 4. Monitor Email Sending

Check logs for email sending activity:
```bash
tail -f logs/celery.log | grep -i "sla reminder"
tail -f logs/django.log | grep -i "email"
```

### 5. Verify Timeline Updates

Check complaint timeline in admin panel or via API:

```python
from apps.complaints.models import Complaint, ComplaintUpdate

complaint = Complaint.objects.get(id="COMPLAINT_UUID")
updates = complaint.updates.all().order_by('-created_at')

for update in updates:
    print(f"{update.update_type}: {update.message}")
    print(f"Metadata: {update.metadata}")
```

## Testing Scenarios

### Scenario 1: First Reminder Only
1. Create complaint due in 26 hours
2. Wait for or trigger first reminder (at 24 hours)
3. Verify email sent
4. Verify `reminder_sent_at` timestamp set
5. Check ComplaintUpdate created

### Scenario 2: Second Reminder
1. Create complaint due in 26 hours
2. Wait for first reminder (at 24 hours)
3. Wait for second reminder (at 6 hours)
4. Verify second reminder email sent
5. Verify `second_reminder_sent_at` timestamp set
6. Check ComplaintUpdate created

### Scenario 3: Escalation After Reminder
1. Create complaint with escalation rules configured
2. Let first reminder be sent
3. Wait for escalation trigger (e.g., 12 hours after reminder)
4. Verify complaint escalated
5. Verify `escalated_at` timestamp set
6. Verify escalation level increased in metadata
7. Verify notification sent to escalation target

### Scenario 4: Complaint Closure
1. Create and resolve a complaint
2. Close the complaint
3. Verify thank you email sent (if enabled in SLA config)
4. Check ComplaintUpdate for closure

### Scenario 5: No Second Reminder (Disabled)
1. Configure SLA with `second_reminder_enabled=False`
2. Create complaint due in 26 hours
3. Wait past second reminder timing
4. Verify no second reminder sent
5. Verify `second_reminder_sent_at` remains null

## Production Configuration

### Celery Beat Schedule

Ensure Celery Beat is configured to run SLA tasks:

```python
# config/celery.py
from celery.schedules import crontab

app.conf.beat_schedule = {
    'check-sla-reminders': {
        'task': 'apps.complaints.tasks.send_sla_reminders',
        'schedule': crontab(minute=0),  # Every hour
    },
    'check-overdue-complaints': {
        'task': 'apps.complaints.tasks.check_overdue_complaints',
        'schedule': crontab(minute=0),  # Every hour
    },
}
```

### Email Configuration

Ensure email backend is configured in settings:

```python
# config/settings/dev.py
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'  # For testing

# config/settings/production.py
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'smtp.your-provider.com'
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = 'your-email@example.com'
EMAIL_HOST_PASSWORD = 'your-password'
DEFAULT_FROM_EMAIL = 'noreply@your-domain.com'
```

### Monitoring

Set up monitoring for:
1. Celery task execution logs
2. Email delivery success/failure
3. Overdue complaints count
4. Escalation activity
5. Reminder sending frequency

## Troubleshooting

### Reminders Not Sending

**Check:**
1. Is Celery Beat running?
2. Is `reminder_hours_before` > `hours_until_due`?
3. Is `reminder_sent_at` already set?
4. Is complaint still open?
5. Check logs: `logs/celery.log`

### Escalation Not Triggering

**Check:**
1. Is escalation rule configured for hospital?
2. Is `is_active=True` on escalation rule?
3. Is trigger condition met (overdue or reminder-based)?
4. Is `reminder_escalation_enabled=True` for reminder-based?
5. Check escalation level hasn't exceeded `max_escalation_level`

### Emails Not Delivered

**Check:**
1. Email backend configuration
2. Email template files exist and are valid
3. Recipient email addresses are valid
4. SMTP server is accessible (for production)
5. Check logs for email sending errors

### Database Migration Issues

If you encounter migration issues with the new `second_reminder_sent_at` field:

```bash
# Check migration status
python manage.py showmigrations complaints

# If needed, create new migration
python manage.py makemigrations complaints

# Apply migration
python manage.py migrate complaints

# Verify field exists
python manage.py dbshell
\dt complaints_complaint
\d complaints_complaint
```

## API Endpoints

### List SLA Configurations
```
GET /api/complaints/sla-configs/
```

### Create SLA Configuration
```
POST /api/complaints/sla-configs/
```

### Update SLA Configuration
```
PUT /api/complaints/sla-configs/{id}/
```

### List Escalation Rules
```
GET /api/complaints/escalation-rules/
```

### Create Escalation Rule
```
POST /api/complaints/escalation-rules/
```

## Best Practices

1. **Start with conservative settings**: Set longer SLA times during testing
2. **Test in stages**: Test first reminders, then second, then escalation
3. **Monitor closely**: Watch logs during initial deployment
4. **Configure per hospital**: Different hospitals may need different SLAs
5. **Use severity/priority**: Configure different SLAs for different complaint types
6. **Document escalation paths**: Ensure staff understand escalation flow
7. **Test email delivery**: Verify emails reach recipients before going live
8. **Plan capacity**: Ensure system can handle email volume at peak times

## Support

For issues or questions:
1. Check logs: `logs/celery.log`, `logs/django.log`
2. Review documentation in `/docs/`
3. Check configuration in `.env`
4. Run test script: `python test_sla_functionality.py`
5. Verify Celery is running: `ps aux | grep celery`

## Changelog

### Version 2.0 (Current)
- ✅ Added second reminder feature
- ✅ Added `second_reminder_sent_at` field to Complaint model
- ✅ Created bilingual second reminder email templates
- ✅ Enhanced `send_sla_reminders()` task for second reminder
- ✅ Updated test script to cover second reminder

### Version 1.0 (Previous)
- Initial SLA system with first reminder
- Escalation rules
- Thank you email feature
- Timeline tracking