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:

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