HH/HIS_SIMULATOR_PATIENT_JOURNEYS_SUMMARY.md

# HIS Simulator - Patient Journeys Summary

## Overview
This document summarizes the patient journeys implemented in the HIS simulator and the survey delivery system.

## Patient Journeys (4 Types)

The HIS simulator supports **4 distinct patient journey types**, each with its own survey template:

### 1. Inpatient Journey (PatientType: 1)
- **Survey Template:** Inpatient Post-Discharge Survey
- **Requirements:** Must have a discharge date
- **Flow:**
  1. Patient admission
  2. Hospital stay
  3. **Discharge event** → Triggers survey
  4. Survey sent via SMS

### 2. OPD Journey (PatientType: 2)
- **Survey Template:** OPD Patient Experience Survey
- **Requirements:** No discharge required (sent after visit)
- **Flow:**
  1. Patient registration
  2. Consultation/visit
  3. **Visit completion** → Triggers survey
  4. Survey sent via SMS

### 3. EMS Journey (PatientType: 3)
- **Survey Template:** EMS Emergency Services Survey
- **Requirements:** No discharge required (sent after emergency visit)
- **Flow:**
  1. Emergency arrival
  2. Emergency treatment
  3. **Visit completion** → Triggers survey
  4. Survey sent via SMS

### 4. Day Case Journey (PatientType: 4)
- **Survey Template:** Day Case Patient Survey
- **Requirements:** Has discharge date (same-day procedure)
- **Flow:**
  1. Patient admission
  2. Procedure/treatment
  3. **Same-day discharge** → Triggers survey
  4. Survey sent via SMS

## Technical Implementation

### HIS Integration Endpoint
- **URL:** `POST /api/integrations/events/`
- **View:** `HISPatientDataView` (in `apps/integrations/views.py`)
- **Service:** `HISAdapter.process_his_data()` (in `apps/integrations/services/his_adapter.py`)

### Patient Type Mapping
The system maps HIS PatientType codes to survey types:

| HIS Code | Survey Type | Template Name |
|----------|-------------|---------------|
| "1" | INPATIENT | Inpatient Post-Discharge Survey |
| "2", "O" | OPD | OPD Patient Experience Survey |
| "3", "E" | EMS | EMS Emergency Services Survey |
| "4" | DAYCASE | Day Case Patient Survey |

### Survey Template Selection Logic
The system searches for appropriate survey templates using a hierarchical approach:

1. **Primary search:** Look for template by patient type keywords, filtered by hospital
2. **Secondary search:** Look for template by patient type keywords, without hospital filter
3. **Fallback 1:** Use any active template for the hospital
4. **Fallback 2:** Use any active template in the system

Search terms (in order of specificity):
- **INPATIENT:** "INPATIENT", "Inpatient"
- **OPD:** "OPD", "Outpatient"
- **EMS:** "EMS", "Emergency"
- **DAYCASE:** "Day Case"

### Data Flow

```
HIS System
    ↓
POST /api/integrations/events/
    ↓
HISPatientDataView
    ↓
HISAdapter.process_his_data()
    ↓
1. Parse patient data
2. Get or create Hospital
3. Get or create Patient
4. Get appropriate SurveyTemplate (based on PatientType)
5. Create SurveyInstance
6. Send survey via SMS (SurveyDeliveryService.deliver_survey)
    ↓
Survey sent to patient's phone number
```

### Patient Data Structure

```json
{
  "FetchPatientDataTimeStampList": [{
    "PatientID": "MRN001",
    "AdmissionID": "ADM001",
    "HospitalID": "1",
    "HospitalName": "Al Hammadi Hospital - Riyadh",
    "PatientType": "1",  // 1=Inpatient, 2=OPD, 3=EMS, 4=Day Case
    "AdmitDate": "28-Jan-2025 09:00",
    "DischargeDate": "01-Feb-2025 14:00",  // Required for Inpatient/Day Case
    "PatientName": "Full Name",
    "Gender": "Male",
    "MobileNo": "0501234567",
    "Email": "email@example.com",
    "DOB": "15-Mar-1985 00:00",
    // ... additional fields
  }],
  "FetchPatientDataTimeStampVisitDataList": [
    // Visit/activity data
  ],
  "Code": 200,
  "Status": "Success"
}
```

## Survey Templates

All survey templates are created via Django management command:
```bash
python manage.py create_his_survey_templates
```

This creates 4 templates for the specified hospital:
1. **Inpatient Post-Discharge Survey** (7 questions)
2. **OPD Patient Experience Survey** (6 questions)
3. **EMS Emergency Services Survey** (6 questions)
4. **Day Case Patient Survey** (6 questions)

## Testing

A comprehensive test script is available:
```bash
python test_all_patient_types.py
```

This script tests all 4 patient types and verifies:
- Survey creation
- Correct template selection
- Survey URL generation
- Database persistence

## Key Features

1. **Patient Deduplication:** Existing patients are updated with new information
2. **Survey Deduplication:** Only one survey per admission ID
3. **Hospital Management:** Automatic hospital creation/lookup
4. **Flexible Template Matching:** Multiple fallback mechanisms ensure a survey is always sent
5. **SMS Delivery:** Surveys are automatically sent via SMS
6. **Status Tracking:** Survey status is tracked (SENT, COMPLETED, etc.)

## Important Notes

1. **Inpatient patients MUST have a discharge date** before a survey is sent
2. **OPD and EMS patients do NOT require discharge dates** (surveys sent after visit)
3. **Day Case patients have discharge dates** (same-day procedures)
4. **Survey templates must be active** (`is_active=True`)
5. **Patient phone number is required** for SMS delivery

## Files Modified/Created

### Core Integration Files
- `apps/integrations/views.py` - HISPatientDataView
- `apps/integrations/services/his_adapter.py` - HISAdapter service
- `apps/integrations/urls.py` - API endpoint configuration

### Survey Templates
- `apps/surveys/management/commands/create_his_survey_templates.py` - Template creation command

### Testing
- `test_all_patient_types.py` - Comprehensive test suite for all patient types

## Summary

The HIS simulator successfully implements **4 patient journey types**, each with:
- Distinct patient classification (Inpatient, OPD, EMS, Day Case)
- Appropriate survey template selection
- Automatic survey creation and delivery
- Patient and hospital management
- Flexible fallback mechanisms

All journeys are tested and working correctly, with surveys being sent via SMS to patients based on their patient type and discharge status.