# Post-Discharge Survey Implementation

## Overview

This implementation replaces the per-stage survey system with a comprehensive post-discharge survey that merges questions from all completed stages into a single survey sent after patient discharge.

## Changes Made

### 1. Model Changes

#### PatientJourneyTemplate Model
- **Added:**
  - `send_post_discharge_survey`: Boolean field to enable/disable post-discharge surveys
  - `post_discharge_survey_delay_hours`: Integer field for delay after discharge (in hours)

#### PatientJourneyStageTemplate Model
- **Removed:**
  - `auto_send_survey`: No longer auto-send surveys at each stage
  - `survey_delay_hours`: No longer needed for individual stage surveys
- **Retained:**
  - `survey_template`: Still linked for collecting questions to merge

### 2. Task Changes

#### process_inbound_event (apps/integrations/tasks.py)
- **New Logic:**
  - Detects `patient_discharged` event code
  - Checks if journey template has `send_post_discharge_survey=True`
  - Schedules `create_post_discharge_survey` task with configured delay
- **Removed:**
  - No longer triggers surveys at individual stage completion

#### create_post_discharge_survey (apps/surveys/tasks.py)
- **New Task:**
  - Fetches all completed stages for the journey
  - Collects survey templates from each completed stage
  - Creates a comprehensive survey template on-the-fly
  - Merges questions from all stages with section headers
  - Sends the comprehensive survey to the patient

### 3. Admin Changes

#### PatientJourneyStageTemplateInline
- **Removed:**
  - `auto_send_survey` from inline fields
- **Retained:**
  - `survey_template` for question configuration

#### PatientJourneyStageTemplateAdmin
- **Removed:**
  - `auto_send_survey` from list_display, list_filter, fieldsets
  - `survey_delay_hours` from fieldsets

#### PatientJourneyTemplateAdmin
- **Added:**
  - New "Post-Discharge Survey" fieldset with:
    - `send_post_discharge_survey`
    - `post_discharge_survey_delay_hours`

## How It Works

### Workflow

1. **Patient Journey Starts:**
   - Patient goes through various stages (admission, treatment, etc.)
   - Each stage has a `survey_template` configured with questions
   - No surveys are sent at this point

2. **Patient Discharges:**
   - System receives `patient_discharged` event via `process_inbound_event`
   - If `send_post_discharge_survey=True` on journey template:
     - Schedules `create_post_discharge_survey` task after configured delay

3. **Comprehensive Survey Created:**
   - Task collects all completed stages
   - Creates new survey template with merged questions
   - Questions organized with section headers for each stage
   - Survey sent to patient via SMS/WhatsApp/Email

4. **Patient Responds:**
   - Patient completes the comprehensive survey
   - System calculates score and processes feedback
   - Negative scores trigger PX Actions (existing functionality)

## Survey Structure

The post-discharge survey includes:

```
Post-Discharge Survey - [Patient Name] - [Encounter ID]

--- Stage 1 Name ---
  [Question 1 from Stage 1]
  [Question 2 from Stage 1]
  ...

--- Stage 2 Name ---
  [Question 1 from Stage 2]
  [Question 2 from Stage 2]
  ...

--- Stage 3 Name ---
  [Question 1 from Stage 3]
  [Question 2 from Stage 3]
  ...
```

## Configuration

### Enabling Post-Discharge Surveys

1. Go to Admin → Patient Journey Templates
2. Select or create a journey template
3. In "Post-Discharge Survey" section:
   - Check "Send post-discharge survey"
   - Set "Post-discharge survey delay (hours)" (default: 24)

### Setting Stage Questions

1. Go to Patient Journey Templates → Edit Template
2. For each stage in "Journey stage templates" section:
   - Select a `Survey template` (contains questions)
   - These questions will be merged into the post-discharge survey

## Benefits

1. **Reduced Survey Fatigue:** One comprehensive survey instead of multiple surveys
2. **Better Patient Experience:** Patients not overwhelmed with frequent surveys
3. **Complete Picture:** Captures feedback for entire hospital stay
4. **Flexible Configuration:** Easy to enable/disable per journey template
5. **Contextual Organization:** Questions grouped by stage for clarity

## Migration Details

**Migration File:** `apps/journeys/migrations/0003_remove_patientjourneystagetemplate_auto_send_survey_and_more.py`

**Changes:**
- Remove `auto_send_survey` from `PatientJourneyStageTemplate`
- Remove `survey_delay_hours` from `PatientJourneyStageTemplate`
- Add `send_post_discharge_survey` to `PatientJourneyTemplate`
- Add `post_discharge_survey_delay_hours` to `PatientJourneyTemplate`
- Make `survey_template` nullable on `PatientJourneyStageTemplate`

## Task Parameters

### create_post_discharge_survey

**Parameters:**
- `journey_instance_id`: UUID of the PatientJourneyInstance

**Returns:**
```python
{
    'status': 'sent' | 'skipped' | 'error',
    'survey_instance_id': str,
    'survey_template_id': str,
    'notification_log_id': str,
    'stages_included': int,
    'total_questions': int,
    'reason': str  # if skipped/error
}
```

**Skip Conditions:**
- No completed stages in journey
- No survey templates found for completed stages

## Audit Events

The implementation creates audit logs for:
- `post_discharge_survey_sent`: When comprehensive survey is created and sent

**Metadata includes:**
- `survey_template`: Name of comprehensive survey
- `journey_instance`: Journey instance ID
- `encounter_id`: Patient encounter ID
- `stages_included`: Number of stages merged
- `total_questions`: Total questions in survey
- `channel`: Delivery channel (sms/whatsapp/email)

## Future Enhancements

Potential improvements:
1. Add per-stage question filtering (optional stages)
2. Allow custom question ordering
3. Add conditional questions based on stage outcomes
4. Implement survey reminders for post-discharge surveys
5. Add analytics comparing pre/post implementation metrics

## Testing Checklist

- [ ] Verify journey template has post-discharge survey enabled
- [ ] Create journey with multiple stages, each with survey templates
- [ ] Complete all stages
- [ ] Send `patient_discharged` event
- [ ] Verify task is scheduled with correct delay
- [ ] Verify comprehensive survey is created
- [ ] Verify all stage questions are merged with section headers
- [ ] Verify survey is sent to patient
- [ ] Test patient survey completion
- [ ] Verify score calculation works correctly
- [ ] Verify negative survey triggers PX Action

## Rollback Plan

If needed, rollback steps:
1. Disable `send_post_discharge_survey` on all journey templates
2. Revert migration: `python manage.py migrate journeys 0002`
3. Manually restore `auto_send_survey` and `survey_delay_hours` fields if needed
4. Update `process_inbound_event` to restore stage survey logic

## Related Documentation

- [Journey Engine](docs/JOURNEY_ENGINE.md)
- [Survey System](docs/IMPLEMENTATION_STATUS.md#survey-system)
- [Notifications](docs/IMPLEMENTATION_STATUS.md#notification-system)
- [PX Action Center](docs/IMPLEMENTATION_STATUS.md#px-action-center)