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()

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()

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()

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

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

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

if not patient:
    messages.error(request, "Patient is required to create an appointment.")
    return self.form_invalid(form)

2. Missing Consent

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

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:

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():

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