421 lines
14 KiB
Markdown
421 lines
14 KiB
Markdown
# Phase 7: Signals, Services & Tasks Implementation Plan
|
|
|
|
## Overview
|
|
Phase 7 focuses on implementing Django signals for automation, service layer for business logic separation, and Celery tasks for background processing in the Tenhal Multidisciplinary Healthcare Platform.
|
|
|
|
## Objectives
|
|
1. **Django Signals** - Automate audit logging, notifications, and workflow triggers
|
|
2. **Service Layer** - Separate business logic from views for better maintainability
|
|
3. **Celery Tasks** - Background processing for reminders, reports, and integrations
|
|
4. **Scheduled Jobs** - Periodic tasks using Celery Beat
|
|
|
|
## Implementation Checklist
|
|
|
|
### Part 1: Celery Setup & Configuration (30 minutes)
|
|
- [x] Celery already configured in settings.py
|
|
- [ ] Create `AgdarCentre/celery.py` - Celery app initialization
|
|
- [ ] Update `AgdarCentre/__init__.py` - Import Celery app
|
|
- [ ] Create `.env` entries for Redis configuration
|
|
- [ ] Test Celery worker connection
|
|
|
|
### Part 2: Django Signals (2-3 hours)
|
|
|
|
#### Core App Signals
|
|
- [ ] Create `core/signals.py`
|
|
- [ ] `post_save` signal for Patient - Create audit log entry
|
|
- [ ] `post_save` signal for User - Send welcome email
|
|
- [ ] `pre_delete` signal for Patient - Soft delete implementation
|
|
- [ ] `post_save` signal for Consent - Notify relevant staff
|
|
|
|
#### Appointments App Signals
|
|
- [ ] Create `appointments/signals.py`
|
|
- [ ] `post_save` signal for Appointment - Status change notifications
|
|
- [ ] `post_save` signal for Appointment (CONFIRMED) - Schedule reminder task
|
|
- [ ] `post_save` signal for Appointment (COMPLETED) - Trigger invoice generation
|
|
- [ ] `post_save` signal for Appointment (CANCELLED) - Cancel reminders
|
|
- [ ] `pre_save` signal for Appointment - Validate time slot conflicts
|
|
|
|
#### Finance App Signals
|
|
- [ ] Create `finance/signals.py`
|
|
- [ ] `post_save` signal for Payment - Update invoice status
|
|
- [ ] `post_save` signal for Invoice (ISSUED) - Send invoice notification
|
|
- [ ] `post_save` signal for Invoice (OVERDUE) - Schedule overdue reminder
|
|
- [ ] `post_save` signal for Payment (COMPLETED) - Send receipt
|
|
|
|
#### Referrals App Signals
|
|
- [ ] Create `referrals/signals.py`
|
|
- [ ] `post_save` signal for Referral (PENDING) - Notify receiving clinic
|
|
- [ ] `post_save` signal for Referral (ACCEPTED) - Notify sending clinic
|
|
- [ ] `post_save` signal for Referral (REJECTED) - Notify sending clinic
|
|
- [ ] `post_save` signal for Referral (COMPLETED) - Update statistics
|
|
|
|
### Part 3: Service Layer (3-4 hours)
|
|
|
|
#### Core Services
|
|
- [ ] Create `core/services.py`
|
|
- [ ] `PatientService` class
|
|
- [ ] `create_patient()` - Patient creation with validation
|
|
- [ ] `update_patient()` - Patient update with audit
|
|
- [ ] `merge_patients()` - Merge duplicate patients
|
|
- [ ] `get_patient_summary()` - Complete patient overview
|
|
- [ ] `FileService` class
|
|
- [ ] `create_file()` - File creation with auto-numbering
|
|
- [ ] `close_file()` - File closure workflow
|
|
- [ ] `reopen_file()` - File reopening workflow
|
|
|
|
#### Appointments Services
|
|
- [ ] Create `appointments/services.py`
|
|
- [ ] `AppointmentService` class
|
|
- [ ] `book_appointment()` - Complete booking workflow
|
|
- [ ] `confirm_appointment()` - Confirmation with validation
|
|
- [ ] `reschedule_appointment()` - Reschedule with conflict check
|
|
- [ ] `cancel_appointment()` - Cancellation with reason
|
|
- [ ] `check_availability()` - Provider availability check
|
|
- [ ] `get_calendar_slots()` - Calendar view generation
|
|
- [ ] `ScheduleService` class
|
|
- [ ] `create_schedule()` - Schedule creation
|
|
- [ ] `check_conflicts()` - Conflict detection
|
|
- [ ] `get_available_slots()` - Available time slots
|
|
|
|
#### Finance Services
|
|
- [ ] Create `finance/services.py`
|
|
- [ ] `InvoiceService` class
|
|
- [ ] `generate_invoice()` - Auto-generate from appointment
|
|
- [ ] `issue_invoice()` - Issue draft invoice
|
|
- [ ] `calculate_totals()` - Calculate invoice totals
|
|
- [ ] `apply_discount()` - Apply discount logic
|
|
- [ ] `mark_paid()` - Mark invoice as paid
|
|
- [ ] `PaymentService` class
|
|
- [ ] `process_payment()` - Payment processing
|
|
- [ ] `refund_payment()` - Refund processing
|
|
- [ ] `allocate_payment()` - Allocate to invoices
|
|
- [ ] `PackageService` class
|
|
- [ ] `activate_package()` - Activate patient package
|
|
- [ ] `consume_session()` - Consume package session
|
|
- [ ] `check_balance()` - Check remaining sessions
|
|
|
|
#### Referrals Services
|
|
- [ ] Create `referrals/services.py`
|
|
- [ ] `ReferralService` class
|
|
- [ ] `create_referral()` - Referral creation with validation
|
|
- [ ] `accept_referral()` - Accept workflow
|
|
- [ ] `reject_referral()` - Reject workflow
|
|
- [ ] `complete_referral()` - Complete workflow
|
|
- [ ] `check_auto_rules()` - Check auto-referral rules
|
|
- [ ] `get_referral_statistics()` - Statistics calculation
|
|
|
|
### Part 4: Celery Tasks (3-4 hours)
|
|
|
|
#### Notification Tasks
|
|
- [ ] Create `core/tasks.py`
|
|
- [ ] `send_email_task()` - Async email sending
|
|
- [ ] `send_sms_task()` - Async SMS sending
|
|
- [ ] `send_whatsapp_task()` - Async WhatsApp sending
|
|
- [ ] `create_notification_task()` - Create in-app notification
|
|
|
|
#### Appointment Tasks
|
|
- [ ] Create `appointments/tasks.py`
|
|
- [ ] `send_appointment_reminder()` - Send reminder (24h, 2h before)
|
|
- [ ] `send_appointment_confirmation()` - Send confirmation
|
|
- [ ] `check_no_shows()` - Check and mark no-shows
|
|
- [ ] `generate_daily_schedule()` - Generate daily schedule report
|
|
- [ ] `sync_calendar()` - Sync with external calendar (future)
|
|
|
|
#### Finance Tasks
|
|
- [ ] Create `finance/tasks.py`
|
|
- [ ] `generate_invoice_from_appointment()` - Auto-generate invoice
|
|
- [ ] `send_invoice_notification()` - Send invoice to patient
|
|
- [ ] `check_overdue_invoices()` - Check and notify overdue
|
|
- [ ] `send_payment_receipt()` - Send payment receipt
|
|
- [ ] `generate_financial_report()` - Generate periodic reports
|
|
- [ ] `process_batch_payments()` - Process batch payments
|
|
|
|
#### Referral Tasks
|
|
- [ ] Create `referrals/tasks.py`
|
|
- [ ] `send_referral_notification()` - Notify receiving clinic
|
|
- [ ] `check_pending_referrals()` - Check pending referrals
|
|
- [ ] `send_referral_reminder()` - Remind about pending referrals
|
|
- [ ] `update_referral_statistics()` - Update statistics
|
|
|
|
#### Integration Tasks
|
|
- [ ] Create `integrations/tasks.py`
|
|
- [ ] `submit_nphies_eligibility()` - NPHIES eligibility check
|
|
- [ ] `submit_nphies_prior_auth()` - NPHIES prior authorization
|
|
- [ ] `submit_nphies_claim()` - NPHIES claim submission
|
|
- [ ] `submit_zatca_invoice()` - ZATCA e-invoice submission
|
|
- [ ] `sync_lab_results()` - Sync lab results
|
|
- [ ] `sync_radiology_results()` - Sync radiology results
|
|
|
|
### Part 5: Celery Beat Scheduled Tasks (1-2 hours)
|
|
|
|
#### Periodic Tasks Configuration
|
|
- [ ] Create `appointments/beat_schedule.py`
|
|
- [ ] Daily at 8:00 AM - Send appointment reminders for today
|
|
- [ ] Every 2 hours - Check for no-shows
|
|
- [ ] Daily at 6:00 PM - Generate next day schedule
|
|
|
|
- [ ] Create `finance/beat_schedule.py`
|
|
- [ ] Daily at 9:00 AM - Check overdue invoices
|
|
- [ ] Weekly on Monday - Generate weekly financial report
|
|
- [ ] Monthly on 1st - Generate monthly financial report
|
|
|
|
- [ ] Create `referrals/beat_schedule.py`
|
|
- [ ] Daily at 10:00 AM - Check pending referrals
|
|
- [ ] Weekly on Friday - Send referral statistics
|
|
|
|
- [ ] Create `integrations/beat_schedule.py`
|
|
- [ ] Every 30 minutes - Sync lab results
|
|
- [ ] Every 30 minutes - Sync radiology results
|
|
- [ ] Daily at 11:00 PM - Submit pending ZATCA invoices
|
|
|
|
### Part 6: Testing & Validation (2-3 hours)
|
|
|
|
#### Signal Tests
|
|
- [ ] Create `tests/test_signals.py`
|
|
- [ ] Test patient creation triggers audit log
|
|
- [ ] Test appointment confirmation triggers reminder
|
|
- [ ] Test payment triggers invoice update
|
|
- [ ] Test referral creation triggers notification
|
|
|
|
#### Service Tests
|
|
- [ ] Create `tests/test_services.py`
|
|
- [ ] Test appointment booking service
|
|
- [ ] Test invoice generation service
|
|
- [ ] Test payment processing service
|
|
- [ ] Test referral workflow service
|
|
|
|
#### Task Tests
|
|
- [ ] Create `tests/test_tasks.py`
|
|
- [ ] Test email sending task
|
|
- [ ] Test reminder task
|
|
- [ ] Test invoice generation task
|
|
- [ ] Test integration tasks
|
|
|
|
#### Integration Tests
|
|
- [ ] Test complete workflows
|
|
- [ ] Book appointment → Generate invoice → Send reminder
|
|
- [ ] Create referral → Notify → Accept → Complete
|
|
- [ ] Issue invoice → Process payment → Send receipt
|
|
|
|
### Part 7: Documentation (1 hour)
|
|
|
|
- [ ] Create `SIGNALS_REFERENCE.md` - Signal documentation
|
|
- [ ] Create `SERVICES_REFERENCE.md` - Service layer documentation
|
|
- [ ] Create `TASKS_REFERENCE.md` - Celery tasks documentation
|
|
- [ ] Update `README.md` - Add Celery setup instructions
|
|
- [ ] Create `CELERY_DEPLOYMENT.md` - Production deployment guide
|
|
|
|
## File Structure
|
|
|
|
```
|
|
AgdarCentre/
|
|
├── celery.py # Celery app initialization
|
|
├── __init__.py # Import Celery app
|
|
│
|
|
core/
|
|
├── signals.py # Core app signals
|
|
├── services.py # Core business services
|
|
├── tasks.py # Core Celery tasks
|
|
│
|
|
appointments/
|
|
├── signals.py # Appointment signals
|
|
├── services.py # Appointment services
|
|
├── tasks.py # Appointment tasks
|
|
├── beat_schedule.py # Scheduled tasks
|
|
│
|
|
finance/
|
|
├── signals.py # Finance signals
|
|
├── services.py # Finance services
|
|
├── tasks.py # Finance tasks
|
|
├── beat_schedule.py # Scheduled tasks
|
|
│
|
|
referrals/
|
|
├── signals.py # Referral signals
|
|
├── services.py # Referral services
|
|
├── tasks.py # Referral tasks
|
|
├── beat_schedule.py # Scheduled tasks
|
|
│
|
|
integrations/
|
|
├── signals.py # Integration signals
|
|
├── services.py # Integration services
|
|
├── tasks.py # Integration tasks
|
|
├── beat_schedule.py # Scheduled tasks
|
|
│
|
|
tests/
|
|
├── test_signals.py # Signal tests
|
|
├── test_services.py # Service tests
|
|
├── test_tasks.py # Task tests
|
|
```
|
|
|
|
## Key Design Patterns
|
|
|
|
### 1. Signal Pattern
|
|
```python
|
|
from django.db.models.signals import post_save
|
|
from django.dispatch import receiver
|
|
|
|
@receiver(post_save, sender=Appointment)
|
|
def appointment_confirmed(sender, instance, created, **kwargs):
|
|
if not created and instance.status == 'CONFIRMED':
|
|
# Schedule reminder task
|
|
send_appointment_reminder.apply_async(
|
|
args=[instance.id],
|
|
eta=instance.start_time - timedelta(hours=24)
|
|
)
|
|
```
|
|
|
|
### 2. Service Layer Pattern
|
|
```python
|
|
class AppointmentService:
|
|
@staticmethod
|
|
def book_appointment(patient, provider, start_time, **kwargs):
|
|
# Validate availability
|
|
if not AppointmentService.check_availability(provider, start_time):
|
|
raise ValidationError("Time slot not available")
|
|
|
|
# Create appointment
|
|
appointment = Appointment.objects.create(
|
|
patient=patient,
|
|
provider=provider,
|
|
start_time=start_time,
|
|
**kwargs
|
|
)
|
|
|
|
# Trigger post-creation tasks
|
|
send_appointment_confirmation.delay(appointment.id)
|
|
|
|
return appointment
|
|
```
|
|
|
|
### 3. Celery Task Pattern
|
|
```python
|
|
from celery import shared_task
|
|
|
|
@shared_task(bind=True, max_retries=3)
|
|
def send_appointment_reminder(self, appointment_id):
|
|
try:
|
|
appointment = Appointment.objects.get(id=appointment_id)
|
|
# Send reminder logic
|
|
send_sms(appointment.patient.phone, f"Reminder: {appointment}")
|
|
except Exception as exc:
|
|
raise self.retry(exc=exc, countdown=60)
|
|
```
|
|
|
|
## Dependencies Already Installed
|
|
|
|
✅ celery>=5.3.4
|
|
✅ redis>=5.0.1
|
|
✅ django-celery-beat>=2.5.0
|
|
✅ django-celery-results>=2.5.1
|
|
|
|
## Environment Variables Needed
|
|
|
|
Add to `.env`:
|
|
```bash
|
|
# Celery Configuration
|
|
CELERY_BROKER_URL=redis://localhost:6379/0
|
|
CELERY_RESULT_BACKEND=redis://localhost:6379/0
|
|
|
|
# Email Configuration (for notifications)
|
|
EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
|
|
EMAIL_HOST=smtp.gmail.com
|
|
EMAIL_PORT=587
|
|
EMAIL_USE_TLS=True
|
|
EMAIL_HOST_USER=your-email@gmail.com
|
|
EMAIL_HOST_PASSWORD=your-app-password
|
|
DEFAULT_FROM_EMAIL=noreply@agdarcentre.sa
|
|
|
|
# SMS Configuration (Twilio)
|
|
TWILIO_ACCOUNT_SID=your-account-sid
|
|
TWILIO_AUTH_TOKEN=your-auth-token
|
|
TWILIO_PHONE_NUMBER=+1234567890
|
|
TWILIO_WHATSAPP_NUMBER=whatsapp:+1234567890
|
|
```
|
|
|
|
## Running Celery
|
|
|
|
### Development
|
|
```bash
|
|
# Terminal 1: Start Redis
|
|
redis-server
|
|
|
|
# Terminal 2: Start Celery Worker
|
|
celery -A AgdarCentre worker -l info
|
|
|
|
# Terminal 3: Start Celery Beat (for scheduled tasks)
|
|
celery -A AgdarCentre beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
|
|
|
|
# Terminal 4: Start Django
|
|
python manage.py runserver
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
# Use supervisor or systemd to manage processes
|
|
# See CELERY_DEPLOYMENT.md for details
|
|
```
|
|
|
|
## Expected Benefits
|
|
|
|
1. **Automation**
|
|
- Automatic appointment reminders
|
|
- Auto-generated invoices
|
|
- Automated notifications
|
|
- Scheduled reports
|
|
|
|
2. **Performance**
|
|
- Background processing of heavy tasks
|
|
- Non-blocking email/SMS sending
|
|
- Async integration calls
|
|
- Improved response times
|
|
|
|
3. **Maintainability**
|
|
- Separated business logic in services
|
|
- Reusable service methods
|
|
- Testable components
|
|
- Clear code organization
|
|
|
|
4. **Reliability**
|
|
- Task retry mechanisms
|
|
- Error handling and logging
|
|
- Transaction management
|
|
- Audit trail automation
|
|
|
|
## Timeline Estimate
|
|
|
|
- **Part 1: Celery Setup** - 30 minutes
|
|
- **Part 2: Signals** - 2-3 hours
|
|
- **Part 3: Services** - 3-4 hours
|
|
- **Part 4: Tasks** - 3-4 hours
|
|
- **Part 5: Beat Schedule** - 1-2 hours
|
|
- **Part 6: Testing** - 2-3 hours
|
|
- **Part 7: Documentation** - 1 hour
|
|
|
|
**Total: 13-18 hours (2-3 days)**
|
|
|
|
## Success Criteria
|
|
|
|
- [ ] All signals properly connected and tested
|
|
- [ ] Service layer methods working correctly
|
|
- [ ] Celery tasks executing successfully
|
|
- [ ] Scheduled tasks running on time
|
|
- [ ] Email/SMS notifications working
|
|
- [ ] Integration tasks functioning
|
|
- [ ] Comprehensive test coverage
|
|
- [ ] Complete documentation
|
|
|
|
## Next Phase Preview
|
|
|
|
**Phase 8: Admin, RBAC & Auditing**
|
|
- Custom Django admin interfaces
|
|
- Enhanced role-based permissions
|
|
- Detailed audit trails
|
|
- Compliance reporting
|
|
- User activity monitoring
|
|
|
|
---
|
|
|
|
**Status:** Ready to implement
|
|
**Priority:** High (enables automation and background processing)
|
|
**Dependencies:** Phase 6 (APIs) completed ✅
|