368 lines
10 KiB
Markdown
368 lines
10 KiB
Markdown
# 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):**
|
|
```python
|
|
# 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):**
|
|
```python
|
|
# 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:**
|
|
```python
|
|
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
|