diff --git a/CONSENT_CHECK_BEFORE_APPOINTMENT_IMPLEMENTATION.md b/CONSENT_CHECK_BEFORE_APPOINTMENT_IMPLEMENTATION.md new file mode 100644 index 00000000..0f7e7bed --- /dev/null +++ b/CONSENT_CHECK_BEFORE_APPOINTMENT_IMPLEMENTATION.md @@ -0,0 +1,429 @@ +# 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 diff --git a/appointments/__pycache__/urls.cpython-312.pyc b/appointments/__pycache__/urls.cpython-312.pyc index a6cf5751..8c9a2079 100644 Binary files a/appointments/__pycache__/urls.cpython-312.pyc and b/appointments/__pycache__/urls.cpython-312.pyc differ diff --git a/appointments/__pycache__/views.cpython-312.pyc b/appointments/__pycache__/views.cpython-312.pyc index 633b7c1f..d73f0bfd 100644 Binary files a/appointments/__pycache__/views.cpython-312.pyc and b/appointments/__pycache__/views.cpython-312.pyc differ diff --git a/appointments/templates/appointments/appointment_form.html b/appointments/templates/appointments/appointment_form.html index d5aaa522..b05a78dd 100644 --- a/appointments/templates/appointments/appointment_form.html +++ b/appointments/templates/appointments/appointment_form.html @@ -179,6 +179,23 @@
{% trans "Checking consent status..." %}
+${data.message}
++ {% trans "Service:" %} ${data.service_type} +
+${data.message}
++ {% trans "Missing:" %} ${missingTypes} +
+ + {% trans "Create Consent" %} + +${data.error}
+{% trans "Could not check consent status. Please try again." %}
+