agdar/CONSENT_CHECK_BEFORE_APPOINTMENT_IMPLEMENTATION.md

# Consent Check Before Appointment Creation - Implementation Complete

## Overview
Successfully implemented consent verification **before** appointment creation, moving the consent check from clinical form creation to the appointment booking stage.

**Implementation Date:** November 11, 2025  
**Status:** ✅ Complete

---

## Problem Statement

### Previous Approach (Issues)
- Consent was only checked when creating clinical documentation (consult/session forms)
- Users could book appointments for patients without valid consent
- Consent validation happened too late in the workflow
- Led to workflow interruptions when staff tried to create clinical forms

### New Approach (Solution)
- Consent is now checked **before** appointment creation
- System validates consent when user clicks "Create Appointment"
- If consent is missing, user is redirected to create consent first
- Prevents booking appointments for patients without proper consent

---

## Implementation Details

### 1. Modified Files

#### `appointments/views.py`

**Changes Made:**

1. **AppointmentCreateView** - Added consent validation in `form_valid()` method:
   - Checks consent before creating appointment
   - Gets service type from clinic specialty
   - Validates required consent types using `ConsentService.verify_consent_for_service()`
   - If consent missing:
     - Shows error message with missing consent types
     - Stores form data in session for later retrieval
     - Redirects to patient detail page (Consents tab)
   - If consent valid:
     - Proceeds with appointment creation
     - Clears pending data from session

2. **AddPatientToSessionView** - Added consent validation for group sessions:
   - Checks consent before adding patient to session
   - Same validation logic as appointment creation
   - Redirects to patient consent page if consent missing
   - Proceeds with adding patient if consent valid

### 2. Key Methods Added

#### `AppointmentCreateView.form_valid()`
```python
def form_valid(self, form):
    """Validate consent before creating appointment."""
    # Get patient and service type
    patient = form.cleaned_data.get('patient')
    clinic = form.cleaned_data.get('clinic')
    service_type = self._get_service_type_from_clinic(clinic)
    
    # Check consent
    has_consent, consent_message = ConsentService.verify_consent_for_service(
        patient, service_type
    )
    
    if not has_consent:
        # Show error and redirect to consent creation
        # Store form data in session
        # Redirect to patient detail → Consents tab
    
    # Consent verified, create appointment
    return self._create_appointment(form)
```

#### `_get_service_type_from_clinic()`
```python
def _get_service_type_from_clinic(self, clinic):
    """Map clinic specialty to service type for consent validation."""
    specialty_to_service = {
        'MEDICAL': 'MEDICAL',
        'NURSING': 'NURSING',
        'ABA': 'ABA',
        'OT': 'OT',
        'SLP': 'SLP',
        'PSYCHOLOGY': 'PSYCHOLOGY',
        'PHYSIOTHERAPY': 'PHYSIOTHERAPY',
        'NUTRITION': 'NUTRITION',
    }
    return specialty_to_service.get(clinic.specialty, 'MEDICAL')
```

#### `_create_appointment()`
```python
def _create_appointment(self, form):
    """Create appointment after consent validation."""
    # Set tenant
    # Generate appointment number
    # Set initial status
    # Save appointment
    # Clear pending data from session
    # Send confirmation notification
```

---

## Workflow Changes

### Old Workflow
```
1. User creates appointment (no consent check)
2. Appointment is booked
3. Patient arrives
4. Staff tries to create clinical form
5. ❌ Consent check fails
6. Staff must go back and create consent
7. Staff returns to create clinical form
```

### New Workflow
```
1. User clicks "Create Appointment"
2. ✅ System checks consent FIRST
3a. If consent valid → Appointment is created
3b. If consent missing:
    - Error message shown
    - User redirected to patient detail → Consents tab
    - Form data saved in session
4. User creates and signs consent
5. User returns to appointment creation
6. Appointment is created successfully
```

---

## User Experience Improvements

### 1. **Early Validation**
- Consent checked at booking time, not at clinical documentation time
- Prevents workflow interruptions later

### 2. **Clear Error Messages**
```
"Cannot create appointment: General treatment consent required. 
Patient must sign required consent forms before booking. 
Missing consent types: GENERAL_TREATMENT, SERVICE_SPECIFIC."
```

### 3. **Guided Workflow**
- System automatically redirects to consent creation page
- Shows which consent types are missing
- Preserves form data for easy return

### 4. **Session Data Preservation**
```python
self.request.session['pending_appointment_data'] = {
    'patient_id': str(patient.id),
    'clinic_id': str(clinic.id),
    'provider_id': str(provider.id),
    'scheduled_date': str(scheduled_date),
    'scheduled_time': str(scheduled_time),
    'service_type': service_type,
    'notes': notes,
}
```

### 5. **Return Notification**
When user returns after signing consent:
```
"Consent forms have been signed. You can now complete the appointment booking."
```

---

## Consent Validation Logic

### Service-Specific Requirements

The system uses `ConsentService.verify_consent_for_service()` which checks:

1. **General Treatment Consent** (Required for ALL services)
   - Must be signed and active
   - Not expired

2. **Service-Specific Consent** (Required for certain services)
   - ABA: ✅ Required
   - OT: ✅ Required
   - SLP: ✅ Required
   - Psychology: ✅ Required
   - Medical: ❌ Not required
   - Nursing: ❌ Not required

3. **Photo/Video Consent** (Required for recording services)
   - ABA: ✅ Required (often involves video recording)
   - Behavioral Therapy: ✅ Required
   - Research: ✅ Required
   - Others: ❌ Not required

### Consent Types Checked
```python
SERVICE_CONSENT_REQUIREMENTS = {
    'ABA': {
        'requires_specific': True,
        'requires_photo_video': True,
    },
    'OT': {
        'requires_specific': True,
        'requires_photo_video': False,
    },
    'SLP': {
        'requires_specific': True,
        'requires_photo_video': False,
    },
    # ... etc
}
```

---

## Integration Points

### 1. **Existing Consent System**
- Uses existing `ConsentService` from `core/services.py`
- Leverages `verify_consent_for_service()` method
- Uses `get_missing_consents()` for detailed feedback

### 2. **Clinical Forms (Unchanged)**
- Clinical forms still have `ConsentRequiredMixin`
- Provides double-check security
- Handles edge cases where consent expires between booking and visit

### 3. **Group Sessions**
- Same consent validation applied to `AddPatientToSessionView`
- Ensures all session participants have valid consent

---

## Error Handling

### 1. **Missing Patient**
```python
if not patient:
    messages.error(request, "Patient is required to create an appointment.")
    return self.form_invalid(form)
```

### 2. **Missing Consent**
```python
if not has_consent:
    error_msg = "Cannot create appointment: {message}. " \
                "Patient must sign required consent forms before booking."
    messages.error(request, error_msg)
    # Redirect to consent creation
```

### 3. **Service Validation**
```python
try:
    participant = SessionService.add_patient_to_session(...)
except ValueError as e:
    messages.error(request, str(e))
```

---

## Testing Checklist

### Manual Testing Required

- [ ] **Test 1: Create appointment with valid consent**
  - Patient has all required consents signed
  - Appointment should be created successfully

- [ ] **Test 2: Create appointment without general consent**
  - Patient missing GENERAL_TREATMENT consent
  - Should show error and redirect to consent page

- [ ] **Test 3: Create appointment without service-specific consent**
  - Patient has general consent but missing ABA-specific consent
  - Should show error listing missing consent types

- [ ] **Test 4: Add patient to group session without consent**
  - Try adding patient to ABA group session
  - Should validate consent before adding

- [ ] **Test 5: Session data preservation**
  - Start creating appointment
  - Get redirected for consent
  - Sign consent
  - Return to appointment form
  - Form data should be preserved

- [ ] **Test 6: Different service types**
  - Test with Medical (no service-specific required)
  - Test with ABA (service-specific + photo/video required)
  - Test with OT (service-specific required)
  - Test with SLP (service-specific required)

### Edge Cases

- [ ] Consent expires between booking and visit (handled by clinical form check)
- [ ] Multiple missing consent types
- [ ] Invalid clinic specialty
- [ ] Session full when returning from consent creation

---

## Benefits

### 1. **Improved Compliance**
- Ensures all appointments have proper consent before booking
- Reduces risk of treating patients without consent

### 2. **Better User Experience**
- Front desk staff know immediately if consent is missing
- No surprises when patient arrives for appointment

### 3. **Workflow Efficiency**
- Consent issues resolved at booking time
- Clinical staff can focus on treatment, not paperwork

### 4. **Audit Trail**
- All consent checks logged
- Clear record of when consent was verified

### 5. **Flexibility**
- Session data preserved for easy return
- User can complete consent and resume booking

---

## Configuration

### Service Type Mapping
Located in `ConsentService.SERVICE_CONSENT_REQUIREMENTS`:

```python
SERVICE_CONSENT_REQUIREMENTS = {
    'MEDICAL': {
        'requires_specific': False,
        'requires_photo_video': False,
    },
    'ABA': {
        'requires_specific': True,
        'requires_photo_video': True,
    },
    # Add more as needed
}
```

### Clinic Specialty Mapping
Located in `AppointmentCreateView._get_service_type_from_clinic()`:

```python
specialty_to_service = {
    'MEDICAL': 'MEDICAL',
    'NURSING': 'NURSING',
    'ABA': 'ABA',
    'OT': 'OT',
    'SLP': 'SLP',
    'PSYCHOLOGY': 'PSYCHOLOGY',
    'PHYSIOTHERAPY': 'PHYSIOTHERAPY',
    'NUTRITION': 'NUTRITION',
}
```

---

## Future Enhancements

### Potential Improvements

1. **Consent Expiry Warning**
   - Show warning if consent expires soon (within 30 days)
   - Prompt for renewal during booking

2. **Bulk Consent Check**
   - Check consent for multiple appointments at once
   - Useful for recurring appointments

3. **Consent Templates**
   - Quick consent creation from appointment form
   - Pre-fill consent with patient data

4. **Notification System**
   - Email/SMS to guardian when consent needed
   - Automated consent renewal reminders

5. **Dashboard Widget**
   - Show patients with missing/expiring consents
   - Quick action buttons for consent creation

---

## Related Documentation

- `CONSENT_MANAGEMENT_100_PERCENT_COMPLETE.md` - Consent system overview
- `CONSENT_ENFORCEMENT_IMPLEMENTATION_COMPLETE.md` - Clinical form consent enforcement
- `core/services.py` - ConsentService implementation
- `core/mixins.py` - ConsentRequiredMixin for clinical forms

---

## Summary

✅ **Successfully implemented consent verification before appointment creation**

**Key Changes:**
1. Consent checked when user clicks "Create Appointment"
2. Missing consent prevents appointment booking
3. User redirected to create consent with preserved form data
4. Same logic applied to group session participant addition
5. Clinical forms retain consent check as secondary validation

**Impact:**
- Improved compliance and workflow efficiency
- Better user experience with early validation
- Reduced workflow interruptions
- Clear error messages and guided resolution

**Status:** Ready for testing and deployment

---

**Implementation completed by:** AI Assistant  
**Date:** November 11, 2025  
**Version:** 1.0