hospital-management/insurance_approvals/README.md

# Insurance Approval Request Module

## Overview

The Insurance Approval Request Module is a comprehensive system for managing insurance pre-authorization and approval requests for any type of medical order in the hospital management system. It provides a universal approval workflow that works with Lab Orders, Radiology Orders, Prescriptions, and any other order type.

## Features

### ✅ Core Functionality

- **Universal Order Support**: Works with any order type using Django's GenericForeignKey
- **Complete Workflow**: 13 status states from Draft to Approved/Denied/Appealed
- **Priority Management**: Routine, Urgent, STAT, Emergency levels
- **Document Management**: Upload and track supporting documents
- **Communication Tracking**: Log all interactions with insurance companies
- **Template System**: Reusable templates for common approval requests
- **Audit Trail**: Complete history of all status changes
- **Multi-tenant**: Full tenant isolation and scoping
- **Expiration Tracking**: Automatic warnings for expiring approvals

### 📊 Status Workflow

```
DRAFT → PENDING_SUBMISSION → SUBMITTED → UNDER_REVIEW
                                              ↓
                                    ┌─────────┴─────────┐
                                    ↓                   ↓
                                APPROVED            DENIED
                                    ↓                   ↓
                            PARTIALLY_APPROVED    APPEAL_SUBMITTED
                                    ↓                   ↓
                                EXPIRED          APPEAL_APPROVED
                                                        ↓
                                                 APPEAL_DENIED
```

## Installation

### 1. App is Already Configured

The app is already added to `INSTALLED_APPS` in `hospital_management/settings.py`:

```python
INSTALLED_APPS = [
    # ... other apps ...
    'insurance_approvals',
]
```

### 2. Create Database Tables

Run the table creation script:

```bash
python3 create_insurance_tables.py
```

This will create 5 tables:
- `insurance_approvals_request`
- `insurance_approvals_document`
- `insurance_approvals_status_history`
- `insurance_approvals_communication_log`
- `insurance_approvals_template`

### 3. Add URLs to Main Project

Add to `hospital_management/urls.py`:

```python
urlpatterns = [
    # ... other patterns ...
    path('insurance-approvals/', include('insurance_approvals.urls')),
]
```

## Usage

### Creating an Approval Request from a Lab Order

```python
from insurance_approvals.models import InsuranceApprovalRequest
from django.contrib.contenttypes.models import ContentType

# Get the lab order
lab_order = LabOrder.objects.get(pk=order_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=lab_order.tenant,
    patient=lab_order.patient,
    insurance_info=lab_order.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(lab_order),
    object_id=lab_order.id,
    request_type='LABORATORY',
    service_description=f"Lab Tests: {', '.join([t.test_name for t in lab_order.tests.all()])}",
    procedure_codes=lab_order.get_procedure_codes(),
    diagnosis_codes=lab_order.get_diagnosis_codes(),
    clinical_justification="Patient presents with symptoms requiring diagnostic testing...",
    requesting_provider=request.user,
    service_start_date=lab_order.order_datetime.date(),
    priority='ROUTINE',
    requested_quantity=lab_order.tests.count()
)
```

### Creating from a Radiology Order

```python
# Get the imaging order
imaging_order = ImagingStudy.objects.get(pk=order_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=imaging_order.tenant,
    patient=imaging_order.patient,
    insurance_info=imaging_order.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(imaging_order),
    object_id=imaging_order.id,
    request_type='RADIOLOGY',
    service_description=imaging_order.study_description,
    procedure_codes=imaging_order.procedure_code,
    diagnosis_codes=imaging_order.get_diagnosis_codes(),
    clinical_justification=imaging_order.clinical_indication,
    requesting_provider=imaging_order.ordering_provider,
    service_start_date=imaging_order.requested_datetime.date(),
    priority=imaging_order.priority,
    requested_quantity=1
)
```

### Creating from a Prescription

```python
# Get the prescription
prescription = Prescription.objects.get(pk=prescription_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=prescription.tenant,
    patient=prescription.patient,
    insurance_info=prescription.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(prescription),
    object_id=prescription.id,
    request_type='PHARMACY',
    service_description=f"{prescription.medication.display_name} - {prescription.dosage_instructions}",
    procedure_codes=prescription.medication.ndc_code,
    diagnosis_codes=prescription.get_diagnosis_codes(),
    clinical_justification=prescription.indication or "As prescribed for patient condition",
    medical_necessity="Medication required for treatment of diagnosed condition",
    requesting_provider=prescription.prescriber,
    service_start_date=prescription.date_written,
    requested_quantity=prescription.quantity,
    requested_units=prescription.quantity,
    priority='ROUTINE'
)
```

### Updating Status

```python
# Approve a request
approval.status = 'APPROVED'
approval.authorization_number = 'AUTH123456'
approval.approved_quantity = approval.requested_quantity
approval.effective_date = timezone.now().date()
approval.expiration_date = timezone.now().date() + timedelta(days=90)
approval.save()

# Deny a request
approval.status = 'DENIED'
approval.denial_reason = "Medical necessity not established"
approval.denial_code = "D001"
approval.save()
```

### Uploading Documents

```python
from insurance_approvals.models import ApprovalDocument

document = ApprovalDocument.objects.create(
    approval_request=approval,
    document_type='MEDICAL_RECORDS',
    title="Patient Medical History",
    description="Complete medical history for past 6 months",
    file=uploaded_file,
    uploaded_by=request.user
)
```

### Logging Communications

```python
from insurance_approvals.models import ApprovalCommunicationLog

communication = ApprovalCommunicationLog.objects.create(
    approval_request=approval,
    communication_type='PHONE',
    contact_person="Jane Smith, Insurance Rep",
    contact_number="1-800-555-0123",
    subject="Status inquiry for authorization",
    message="Called to check on status of pending authorization",
    response="Authorization is under review, expect decision within 48 hours",
    outcome="Pending - follow up in 2 days",
    follow_up_required=True,
    follow_up_date=timezone.now().date() + timedelta(days=2),
    communicated_by=request.user
)
```

## Integration with Existing Order Models

Add these methods to your order models (LabOrder, ImagingStudy, Prescription, etc.):

```python
from django.contrib.contenttypes.fields import GenericRelation

class LabOrder(models.Model):
    # ... existing fields ...
    
    # Add this field
    approval_requests = GenericRelation(
        'insurance_approvals.InsuranceApprovalRequest',
        content_type_field='content_type',
        object_id_field='object_id',
        related_query_name='lab_order'
    )
    
    def requires_insurance_approval(self):
        """Check if this order requires insurance approval."""
        return True  # All orders require approval per requirements
    
    def get_active_approval(self):
        """Get the active approval for this order."""
        from django.utils import timezone
        return self.approval_requests.filter(
            status__in=['APPROVED', 'PARTIALLY_APPROVED', 'APPEAL_APPROVED'],
            expiration_date__gte=timezone.now().date()
        ).first()
    
    def has_valid_approval(self):
        """Check if order has a valid, non-expired approval."""
        approval = self.get_active_approval()
        return approval is not None and not approval.is_expired
    
    def create_approval_request(self, user):
        """Helper method to create an approval request for this order."""
        from insurance_approvals.models import InsuranceApprovalRequest
        from django.contrib.contenttypes.models import ContentType
        
        return InsuranceApprovalRequest.objects.create(
            tenant=self.tenant,
            patient=self.patient,
            insurance_info=self.patient.insurance_info.first(),
            content_type=ContentType.objects.get_for_model(self),
            object_id=self.id,
            request_type='LABORATORY',
            service_description=self.get_service_description(),
            procedure_codes=self.get_procedure_codes(),
            diagnosis_codes=self.get_diagnosis_codes(),
            clinical_justification=self.get_clinical_justification(),
            requesting_provider=user,
            service_start_date=self.order_datetime.date(),
            priority=self.priority or 'ROUTINE'
        )
```

## URL Patterns

The module provides these URL patterns:

```
/insurance-approvals/                                    # Dashboard
/insurance-approvals/list/                               # List all approvals
/insurance-approvals/<id>/                               # Detail view
/insurance-approvals/create/                             # Create new approval
/insurance-approvals/<id>/edit/                          # Edit approval
/insurance-approvals/<id>/submit/                        # Submit for approval
/insurance-approvals/create-from-order/<ct_id>/<obj_id>/ # Create from order
/insurance-approvals/htmx/<id>/update-status/            # HTMX: Update status
/insurance-approvals/htmx/<id>/upload-document/          # HTMX: Upload document
/insurance-approvals/htmx/<id>/log-communication/        # HTMX: Log communication
/insurance-approvals/htmx/dashboard-stats/               # HTMX: Dashboard stats
```

## Admin Interface

Access the admin interface at:
```
http://127.0.0.1:8000/admin/insurance_approvals/
```

Features:
- Color-coded status badges
- Priority indicators
- Expiration warnings
- Inline document management
- Status history tracking
- Communication logs
- Advanced filtering and search

## Models

### InsuranceApprovalRequest
Main model for approval requests with:
- Patient and insurance information
- Service details and codes
- Clinical justification
- Status workflow
- Approval/denial details
- Expiration tracking

### ApprovalDocument
Supporting documents with:
- Document type classification
- File upload
- Metadata tracking

### ApprovalStatusHistory
Audit trail with:
- Status transitions
- Change reasons
- User tracking
- Timestamps

### ApprovalCommunicationLog
Communication tracking with:
- Communication type
- Contact information
- Message and response
- Follow-up management

### ApprovalTemplate
Reusable templates with:
- Insurance company specific
- Procedure specific
- Required documentation
- Usage tracking

## API Integration (Future)

The module is designed to support REST API integration:

```python
# Example API endpoint structure
GET    /api/insurance-approvals/          # List approvals
POST   /api/insurance-approvals/          # Create approval
GET    /api/insurance-approvals/{id}/     # Get approval details
PUT    /api/insurance-approvals/{id}/     # Update approval
PATCH  /api/insurance-approvals/{id}/     # Partial update
DELETE /api/insurance-approvals/{id}/     # Delete approval
POST   /api/insurance-approvals/{id}/submit/  # Submit approval
POST   /api/insurance-approvals/{id}/documents/  # Upload document
GET    /api/insurance-approvals/{id}/history/   # Get status history
```

## Best Practices

1. **Always create approval requests before processing orders**
2. **Upload all required documents before submission**
3. **Log all communications with insurance companies**
4. **Set appropriate priorities for urgent cases**
5. **Monitor expiration dates and renew before expiry**
6. **Use templates for common approval types**
7. **Keep clinical justifications detailed and specific**
8. **Track denial reasons for appeal preparation**

## Troubleshooting

### Common Issues

**Issue**: Approval request not showing in list
- **Solution**: Check tenant filtering, ensure user has correct tenant access

**Issue**: Cannot upload documents
- **Solution**: Check MEDIA_ROOT and MEDIA_URL settings, ensure directory permissions

**Issue**: Status not updating
- **Solution**: Check user permissions, ensure status transition is valid

**Issue**: Related order not showing
- **Solution**: Ensure GenericRelation is added to order model

## Support

For issues or questions:
1. Check this README
2. Review the admin interface
3. Check model documentation in `models.py`
4. Review view logic in `views.py`

## License

Part of the Hospital Management System v4 project.