# 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 ✅