HH/PUBLIC_FORM_4_LEVEL_UPDATE.md

# Public Complaint Form - 4-Level Hierarchy Implementation

## Overview
Updated the public complaint form at `/core/public/submit/` to support the complete 4-level SHCT taxonomy hierarchy instead of the previous 2-level system.

## Changes Made

### 1. API Endpoint Update (`apps/complaints/ui_views.py`)
**Function: `api_load_categories`**
- Added `level` and `domain_type` fields to the returned category data
- Updated ordering to include `level` field for proper hierarchy display
- Now returns complete taxonomy structure with all 4 levels

### 2. View Update (`apps/complaints/ui_views.py`)
**Function: `public_complaint_submit`**
- Updated to handle all 4 taxonomy levels:
  - `domain_id` (Level 1 - Domain)
  - `category_id` (Level 2 - Category)
  - `subcategory_id` (Level 3 - Subcategory)
  - `classification_id` (Level 4 - Classification)
- Added validation for Domain, Category, and Subcategory (Classification is optional)
- Updated Complaint creation to populate all 4 fields:
  - `domain` = ComplaintCategory instance (FK)
  - `category` = ComplaintCategory instance (FK)
  - `subcategory` = category code (CharField)
  - `classification` = category code (CharField)

### 3. Template Update (`templates/complaints/public_complaint_form.html`)
**Complete rewrite with 4-level cascading dropdowns**

#### Features:
1. **4-Level Cascading Dropdowns**
   - Domain (Level 1) - Required
   - Category (Level 2) - Required
   - Subcategory (Level 3) - Required
   - Classification (Level 4) - Optional

2. **Dynamic Loading**
   - Domains load when hospital is selected
   - Categories load when domain is selected
   - Subcategories load when category is selected
   - Classifications load when subcategory is selected

3. **Bilingual Support**
   - Automatically detects current language (English/Arabic)
   - Displays category names in correct language
   - Shows descriptions in correct language

4. **Contextual Descriptions**
   - Each level shows a description box when selected
   - Descriptions help users understand what each category entails
   - Descriptions update dynamically as user selects options

5. **Smart Visibility**
   - Lower-level dropdowns only appear when parent is selected
   - Clear all child selections when parent changes
   - Hide/show containers based on available options

6. **User Experience**
   - Loading spinner during form submission
   - Success modal with reference number
   - SweetAlert2 for error messages
   - Form reset after successful submission

## Taxonomy Structure

### Level 1: Domain (3 domains)
1. **CLINICAL / سريري**
2. **MANAGEMENT / إداري**
3. **RELATIONSHIPS / علاقات**

### Level 2: Category (8 categories)
- Quality / الجودة
- Safety / السلامة
- Institutional Issues / القضايا المؤسسية
- Accessibility / سهولة الوصول
- Communication / التواصل
- Humanness / Caring / الإنسانية / الرعاية
- Consent / الموافقة
- Confidentiality / الخصوصية

### Level 3: Subcategory (20 subcategories)
Examples:
- Examination / الفحص
- Patient Journey / رحلة المريض
- Medication & Vaccination / الأدوية واللقاحات
- Administrative Policies / السياسات الإدارية
- Access / الوصول
- Delays / التأخير
- And more...

### Level 4: Classification (75 classifications)
Granular complaint types like:
- "Wait time too long for appointment"
- "Poor doctor communication"
- "Hospital cleanliness issues"
- "Billing errors"
- And 71 more...

## Technical Details

### JavaScript Functions

#### `loadDomains(hospitalId)`
- Loads Level 1 categories (domains) from API
- Filters by hospital_id
- Shows only categories with `level === 1`

#### `loadCategories(domainId)`
- Loads Level 2 categories
- Filters by `level === 2` and `parent_id == domainId`
- Shows/hides container based on available options

#### `loadSubcategories(categoryId)`
- Loads Level 3 categories
- Filters by `level === 3` and `parent_id == categoryId`
- Required field

#### `loadClassifications(subcategoryId)`
- Loads Level 4 categories
- Filters by `level === 4` and `parent_id == subcategoryId`
- Optional field

#### `showDescription(categoryId, level)`
- Displays category description for selected level
- Shows in correct language (English/Arabic)
- Hides if no description available

### Event Handlers

1. **Hospital Change**
   - Loads domains
   - Clears all taxonomy selections
   - Hides all descriptions

2. **Domain Change**
   - Loads categories
   - Shows domain description
   - Clears child selections and descriptions

3. **Category Change**
   - Loads subcategories
   - Shows category description
   - Clears child selections and descriptions

4. **Subcategory Change**
   - Loads classifications
   - Shows subcategory description
   - Clears classification selection and description

5. **Classification Change**
   - Shows classification description

## Form Fields

### Required Fields:
- Name
- Email Address
- Phone Number
- Hospital
- Domain
- Category
- Subcategory
- Complaint Description

### Optional Fields:
- Classification (Level 4)

## Database Schema

Complaint model fields:
```python
domain = models.ForeignKey(
    ComplaintCategory,
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name='+',
    limit_choices_to={'level': 1}  # Level 1 only
)
category = models.ForeignKey(
    ComplaintCategory,
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name='+',
    limit_choices_to={'level': 2}  # Level 2 only
)
subcategory = models.CharField(
    max_length=50,
    blank=True,
    help_text='Code of the subcategory (Level 3)'
)
classification = models.CharField(
    max_length=50,
    blank=True,
    help_text='Code of the classification (Level 4)'
)
```

## Testing Checklist

- [ ] Verify domains load when hospital is selected
- [ ] Verify categories load when domain is selected
- [ ] Verify subcategories load when category is selected
- [ ] Verify classifications load when subcategory is selected
- [ ] Test cascading behavior (clearing child selections)
- [ ] Test required field validation
- [ ] Test form submission with all 4 levels
- [ ] Test form submission with only 3 levels (no classification)
- [ ] Verify bilingual support (English/Arabic)
- [ ] Verify descriptions display correctly
- [ ] Test error handling
- [ ] Verify success modal displays with reference number

## Benefits

1. **More Precise Classification**
   - Users can now select from 75 specific classifications instead of generic categories
   - Better data for analytics and reporting
   - More accurate assignment to departments

2. **Improved User Experience**
   - Step-by-step selection reduces cognitive load
   - Descriptions help users understand their choices
   - Optional 4th level provides flexibility

3. **Better Analytics**
   - More granular complaint tracking
   - Better trend identification
   - Improved root cause analysis

4. **Compliance**
   - Aligns with Saudi Healthcare Complaint Taxonomy (SHCT)
   - Meets regulatory requirements
   - Standardizes complaint classification

## Migration Notes

- Database already has SHCT taxonomy data loaded
- All 106 categories are in place (3 domains + 8 categories + 20 subcategories + 75 classifications)
- No additional migrations needed for this change
- Backward compatible with existing complaints (domain, category, subcategory, classification fields exist)

## Future Enhancements

- Add autocomplete search for faster selection
- Include icons for each domain/category
- Show complaint examples for each classification
- Add "suggested classification" based on description (AI-powered)
- Multi-language support for more languages