agdar/PACKAGE_APPOINTMENTS_NEW_WORKFLOW_PLAN.md

Package Appointments - New Workflow Implementation Plan

Date: November 18, 2025

---

📋 REQUIREMENTS CLARIFICATION

Current Understanding (CORRECTED):

Package Assignment Logic:

• Packages are NOT pre-purchased by patients
• Packages exist as templates in the system
• When booking an appointment with a package:
  • User selects patient
  • System shows ALL available packages (not just patient's purchases)
  • User selects a package
  • System creates PackagePurchase at this moment (assigns package to patient)
  • Then schedules appointments from that package

---

🎯 NEW WORKFLOW REQUIREMENTS

1. Package Creation (Admin Panel) ✅ Already Exists

• Admin creates packages with:
  • Set of services
  • Number of sessions per service
  • Optional: default clinic, provider restrictions, validity period

2. Booking Workflow (User Side) 🔄 NEEDS IMPLEMENTATION

Step 1: Start Appointment Booking

• User clicks "Book Appointment"
• Options:
  • Normal booking flow (single session)
  • "Use Package" option

Step 2: Selecting "Use Package" 🆕 NEW FEATURE

Modal Window Should Show:

• Patient selection dropdown (if not already selected)
• After patient selected, show TWO categories of packages:
  1. Packages already assigned to this patient (existing PackagePurchases)
  2. Available packages not yet assigned (all active Packages)

Key Difference from Current Implementation:

• Current: Only shows PackagePurchases for patient ❌
• Required: Show ALL available Packages + existing PackagePurchases ✅

Step 3: Linking Package to Patient (Backend) 🆕 NEW LOGIC

When user selects an unassigned package:

• System creates new PackagePurchase record
• Links package to patient
• Tracks:
  • Remaining sessions
  • Services included
  • Used vs unused appointments
  • Purchase date
  • Expiry date

3. Dynamic Clinic & Provider Filtering 🆕 NEW FEATURE

Populate Clinics Based on Package Services

After package selection:

• Extract services from package
• Filter clinics that can perform these services
• Show only relevant clinics

Provider Selection

• Single provider OR multiple providers (multi-select)
• Filter providers by:
  • Selected clinics
  • Services in package
  • Provider availability

4. Auto-Scheduling ✅ Partially Exists, Needs Enhancement

After selecting clinics & providers:

• Show "Auto Schedule" button
• Calculate best available slots considering:
  • Provider availability
  • Clinic hours
  • Remaining package sessions
  • Service duration
• Pre-fill appointment details for confirmation

5. Final Confirmation ✅ Already Exists

• User confirms appointment
• System deducts session from package
• Appointment logged and linked to package

---

🔧 IMPLEMENTATION PLAN

Phase 1: Revert Incorrect Changes ⚠️ CRITICAL

Current Issue:

• Form only shows PackagePurchases for patient
• Should show ALL Packages + existing PackagePurchases

Files to Modify:

1. appointments/forms.py - Change queryset logic
2. appointments/views.py - Update validation logic
3. appointments/templates/appointments/appointment_form.html - Update UI

Phase 2: Implement Modal for Package Selection 🆕

New Components:

1. Create modal template for package selection
2. Add AJAX endpoint to fetch packages
3. Separate assigned vs unassigned packages
4. Handle package assignment on selection

Files to Create/Modify:

• appointments/templates/appointments/partials/package_selection_modal.html
• appointments/views.py - Add assign_package_to_patient view
• appointments/api_views.py - Add API endpoint for package list

Phase 3: Dynamic Clinic & Provider Filtering 🆕

Implementation:

1. Extract services from selected package
2. Filter clinics by services
3. Multi-select provider dropdown
4. AJAX-based filtering

Files to Modify:

• appointments/forms.py - Add dynamic filtering
• appointments/templates/appointments/appointment_form.html - Add multi-select
• JavaScript for dynamic updates

Phase 4: Enhanced Auto-Scheduling 🔄

Enhancements:

1. Support multiple providers
2. Better slot calculation
3. Preview before confirmation
4. Batch appointment creation

Files to Modify:

• appointments/package_integration_service.py
• appointments/views.py - schedule_package_view

Phase 5: Testing & Validation ✅

• Test package assignment flow
• Test multi-provider scheduling
• Test clinic filtering
• Test auto-scheduling

---

📊 COMPARISON: CURRENT vs REQUIRED

Feature	Current Implementation	Required Implementation
Package Display	Only PackagePurchases for patient	ALL Packages + PackagePurchases
Package Assignment	Pre-purchased in finance	Assigned during appointment booking
Clinic Selection	Manual	Auto-filtered by package services
Provider Selection	Single provider	Single OR multiple providers
Auto-Schedule	Basic	Enhanced with multi-provider support
Modal UI	No modal	Modal for package selection

---

🗂️ DATABASE SCHEMA (No Changes Needed)

Current schema already supports the workflow:

finance.Package (Template)
    ↓
finance.PackagePurchase (Assignment to Patient)
    ↓
appointments.Appointment (Individual Sessions)

Key Fields:

• PackagePurchase.patient - Links to patient
• PackagePurchase.package - Links to package template
• PackagePurchase.purchase_date - When assigned
• PackagePurchase.sessions_used - Tracking
• Appointment.package_purchase - Links appointment to package

---

🔄 WORKFLOW DIAGRAM

1. User: "Book Appointment"
   ↓
2. User: Select "Use Package"
   ↓
3. Modal Opens:
   - Select Patient
   - Show Packages:
     * Already Assigned (PackagePurchases)
     * Available (Packages)
   ↓
4. User Selects Package
   ↓
5. System:
   - If new package → Create PackagePurchase
   - If existing → Use existing PackagePurchase
   ↓
6. System:
   - Extract services from package
   - Filter clinics by services
   - Show filtered clinics
   ↓
7. User:
   - Select clinic(s)
   - Select provider(s) - multi-select
   ↓
8. User: Click "Auto Schedule"
   ↓
9. System:
   - Calculate available slots
   - Consider all providers
   - Create appointments
   ↓
10. User: Confirm
    ↓
11. System:
    - Save appointments
    - Increment sessions_used
    - Link to PackagePurchase

---

🚨 CRITICAL CHANGES NEEDED

1. Form Queryset Logic ⚠️ HIGH PRIORITY

Current (INCORRECT):

# Shows only PackagePurchases for patient
self.fields['package_purchase'].queryset = PackagePurchase.objects.filter(
    patient=patient,
    status='ACTIVE'
).filter(sessions_used__lt=F('total_sessions'))

Required (CORRECT):

# Need TWO separate fields or combined logic:
# 1. Show existing PackagePurchases for patient
# 2. Show all available Packages

# Option A: Two separate dropdowns
self.fields['existing_package'].queryset = PackagePurchase.objects.filter(...)
self.fields['new_package'].queryset = Package.objects.filter(is_active=True)

# Option B: Combined with grouping in template
# Return both and handle in JavaScript

2. Package Assignment Logic 🆕 NEW

Need to Add:

def assign_package_to_patient(request):
    """
    Create PackagePurchase when user selects unassigned package.
    """
    package_id = request.POST.get('package_id')
    patient_id = request.POST.get('patient_id')
    
    # Create PackagePurchase
    package_purchase = PackagePurchase.objects.create(
        patient=patient,
        package=package,
        purchase_date=date.today(),
        expiry_date=date.today() + timedelta(days=package.validity_days),
        total_sessions=package.total_sessions,
        sessions_used=0,
        status='ACTIVE'
    )
    
    return JsonResponse({'package_purchase_id': package_purchase.id})

3. Modal UI 🆕 NEW

Need to Create:

• Modal template with package selection
• AJAX calls for package list
• Visual distinction between assigned/unassigned
• Package assignment on selection

---

📝 IMPLEMENTATION STEPS

Step 1: Revert Previous Changes ⚠️

• Revert form queryset to show all packages
• Remove patient-only filtering
• Update validation logic

Step 2: Create Modal UI 🆕

• Create modal template
• Add package selection logic
• Implement AJAX endpoints
• Add visual indicators

Step 3: Implement Package Assignment 🆕

• Create assignment view
• Add validation
• Handle PackagePurchase creation
• Link to appointment booking

Step 4: Dynamic Filtering 🆕

• Extract services from package
• Filter clinics by services
• Implement multi-select for providers
• Add AJAX updates

Step 5: Enhanced Auto-Schedule 🔄

• Support multiple providers
• Improve slot calculation
• Add preview functionality
• Batch create appointments

Step 6: Testing ✅

• Test complete workflow
• Test edge cases
• Validate data integrity
• User acceptance testing

---

⏱️ ESTIMATED EFFORT

Phase	Effort	Priority
Revert Changes	1 hour	HIGH
Modal UI	4 hours	HIGH
Package Assignment	2 hours	HIGH
Dynamic Filtering	3 hours	MEDIUM
Enhanced Auto-Schedule	3 hours	MEDIUM
Testing	2 hours	HIGH
TOTAL	15 hours

---

🎯 NEXT STEPS

1. Get User Confirmation on this plan
2. Revert incorrect changes from previous implementation
3. Implement modal-based package selection
4. Add package assignment logic
5. Implement dynamic filtering
6. Enhance auto-scheduling
7. Test complete workflow

---

📞 QUESTIONS FOR USER

1. Should we show package prices in the selection modal?
2. Should there be approval workflow for package assignment?
3. Can users assign expired packages?
4. Should we limit how many times a package can be assigned?
5. What happens if a package is partially used and user wants to reassign?

---

Status: PLAN READY - AWAITING USER CONFIRMATION TO PROCEED

Next Action: User to confirm plan, then toggle to ACT MODE for implementation