HH/apps/complaints/COMPLAINT_FORM_DJANGO_FORM_IMPLEMENTATION.md

Complaint Form Django Form Implementation

Summary

The complaint form has been successfully refactored to use Django's built-in form rendering instead of manual HTML fields and complex AJAX calls.

Changes Made

1. New ComplaintForm in apps/complaints/forms.py

Fields Included:

• patient - Required dropdown, filtered by user hospital
• hospital - Required dropdown, pre-filtered by user permissions
• department - Optional dropdown, filtered by selected hospital
• staff - Optional dropdown, filtered by selected department
• encounter_id - Optional text field
• description - Required textarea

Fields Removed (AI will determine):

• category - AI will determine automatically
• subcategory - AI will determine automatically
• source - Set to 'staff' for authenticated users

Features:

• User permission filtering (PX admins see all, hospital users see only their hospital)
• Dependent queryset initialization (departments load when hospital is pre-selected)
• Full Django form validation
• Clean error messages

2. Updated complaint_create View in apps/complaints/ui_views.py

Changes:

• Uses ComplaintForm(request.POST, user=request.user) for form handling
• Handles form.is_valid() validation
• Sets AI defaults before saving:
  • title = 'Complaint' (AI will generate)
  • category = None (AI will determine)
  • subcategory = '' (AI will determine)
  • source = 'staff' (default for authenticated users)
  • priority = 'medium' (AI will update)
  • severity = 'medium' (AI will update)
• Creates initial update record
• Triggers AI analysis via Celery
• Logs audit trail
• Handles hospital parameter for form pre-selection

3. Updated Template templates/complaints/complaint_form.html

Changes:

• Uses Django form rendering: {{ form.field }}
• Removed all manual HTML input fields
• Removed complex AJAX endpoints
• Kept minimal JavaScript:
  • Hospital change → reload form with hospital parameter
  • Department change → load staff via /complaints/ajax/physicians/
  • Form validation

Removed AJAX Endpoints:

• /api/organizations/departments/ - No longer needed
• /api/organizations/patients/ - No longer needed
• /complaints/ajax/get-staff-by-department/ - Changed to /complaints/ajax/physicians/

Structure:

• Patient Information section
• Organization section (Hospital, Department, Staff)
• Complaint Details section (Description)
• AI Classification info alert
• SLA Information alert
• Action buttons

Benefits

1. Simpler Code - Django handles form rendering and validation
2. Better Error Handling - Form validation with clear error messages
3. Less JavaScript - Only minimal JS for dependent dropdowns
4. Cleaner Separation - Business logic in forms, presentation in templates
5. User Permissions - Automatic filtering based on user role
6. AI Integration - Category, subcategory, severity, and priority determined by AI

Testing Checklist

• Form loads correctly for PX admin users
• Form loads correctly for hospital users (filtered to their hospital)
• Hospital dropdown pre-fills when hospital parameter in URL
• Department dropdown populates when hospital selected
• Staff dropdown populates when department selected
• Form validation works for required fields
• Complaint saves successfully
• AI analysis task is triggered after creation
• User is redirected to complaint detail page
• Back links work for both regular and source users

Related Files

• apps/complaints/forms.py - ComplaintForm definition
• apps/complaints/ui_views.py - complaint_create view
• templates/complaints/complaint_form.html - Form template
• apps/complaints/urls.py - URL configuration
• apps/complaints/tasks.py - AI analysis task

Notes

• The form uses a simple reload approach for hospital selection to keep JavaScript minimal
• Staff loading still uses AJAX because it's a common pattern and provides good UX
• All AI-determined fields are hidden from the user interface
• The form is bilingual-ready using Django's translation system