HH/docs/COMPLAINT_SEEDING_GUIDE.md

Complaint Seeding Guide

Overview

The seed_complaints management command creates realistic test complaint data with bilingual support (English and Arabic) for testing the PX360 complaint management system.

Features

• Bilingual Support: Creates complaints in both English and Arabic (70% Arabic, 30% English by default)
• Staff-Mentioned Complaints: ~60% of complaints mention specific staff members (nurses, physicians, admin staff)
• General Complaints: ~40% of complaints are general (facility, billing, wait time, etc.)
• Severity Distribution: Critical, High, Medium, Low complaints
• Priority Distribution: Urgent, High, Medium, Low priorities
• Category-Based: Matches complaints to appropriate categories (clinical_care, staff_behavior, facility, wait_time, billing, communication, other)
• Timeline Entries: Automatically creates initial timeline entries
• Reference Numbers: Generates unique complaint reference numbers
• AI Analysis: Django signals will automatically trigger AI analysis for new complaints

Prerequisites

Before running this command, ensure you have:

1. Active Hospitals: Hospitals with status='active'

   python manage.py seed_departments
   

2. Complaint Categories: System-wide complaint categories

   python manage.py seed_complaint_configs
   

3. Staff Data (optional but recommended): Staff members in the database

   python manage.py seed_staff
   

Usage

Basic Usage (Create 10 complaints)

python manage.py seed_complaints

This creates:

• 10 total complaints
• 7 Arabic complaints (70%)
• 3 English complaints (30%)
• 6 staff-mentioned complaints (60%)
• 4 general complaints (40%)
• All with status: OPEN

Custom Number of Complaints

python manage.py seed_complaints --count 50

Create 50 complaints with default percentages.

Custom Language Distribution

python manage.py seed_complaints --count 20 --arabic-percent 50

Create 20 complaints:

• 10 Arabic (50%)
• 10 English (50%)

Target Specific Hospital

python manage.py seed_complaints --hospital-code ALH

Create complaints only for hospital with code 'ALH'.

Custom Staff-Mention Percentage

python manage.py seed_complaints --staff-mention-percent 80

Create complaints with 80% staff-mentioned and 20% general.

Preview Without Creating (Dry Run)

python manage.py seed_complaints --dry-run

Shows what would be created without actually creating complaints.

Clear Existing Complaints First

python manage.py seed_complaints --clear

Deletes all existing complaints before creating new ones.

Combined Options

python manage.py seed_complaints --count 100 --arabic-percent 60 --staff-mention-percent 70 --hospital-code ALH --clear

Create 100 complaints for hospital 'ALH':

• 60 Arabic, 40 English
• 70 staff-mentioned, 30 general
• Delete existing complaints first

Command Arguments

Argument	Type	Default	Description
--count	int	10	Number of complaints to create
--arabic-percent	int	70	Percentage of Arabic complaints (0-100)
--hospital-code	str	-	Target hospital code (default: all hospitals)
--staff-mention-percent	int	60	Percentage of staff-mentioned complaints (0-100)
--dry-run	flag	False	Preview without making changes
--clear	flag	False	Delete existing complaints first

Complaint Templates

English Complaints

Staff-Mentioned Examples:

• Rude behavior from nurse during shift
• Physician misdiagnosed my condition
• Nurse ignored call button for over 30 minutes
• Physician did not explain treatment plan clearly
• Nurse made medication error
• Admin staff was unhelpful with billing inquiry
• Nurse was compassionate and helpful
• Physician provided excellent care

General Complaints:

• Long wait time in emergency room
• Room was not clean upon admission
• Air conditioning not working properly
• Billing statement has incorrect charges
• Difficulty getting prescription refills
• Parking is inadequate for visitors
• Food quality has declined

Arabic Complaints

Staff-Mentioned Examples:

• سلوك غير مهذب من الممرضة أثناء المناوبة
• الطبيب تشخص خطأ في حالتي
• الممرضة تجاهلت زر الاستدعاء لأكثر من 30 دقيقة
• الطبيب لم يوضح خطة العلاج بوضوح
• الممرضة ارتكبت خطأ في الدواء
• موظف الإدارة كان غير مفيد في استفسار الفوترة
• الممرضة كانت متعاطفة ومساعدة
• الطبيب قدم رعاية ممتازة

General Complaints:

• وقت انتظار طويل في الطوارئ
• الغرفة لم تكن نظيفة عند القبول
• التكييف لا يعمل بشكل صحيح
• كشف الفاتورة يحتوي على رسوم غير صحيحة
• صعوبة الحصول على وصفات طبية
• مواقف السيارات غير كافية للزوار
• جودة الطعام انخفضت

Complaint Categories

Code	English Name	Arabic Name
clinical_care	Clinical Care	الرعاية السريرية
staff_behavior	Staff Behavior	سلوك الموظفين
facility	Facility & Environment	المرافق والبيئة
wait_time	Wait Time	وقت الانتظار
billing	Billing	الفواتير
communication	Communication	التواصل
other	Other	أخرى

Severity and Priority Distribution

Staff-Mentioned Complaints

• Critical/Urgent: Medication errors, misdiagnosis, severe rude behavior
• High/High: Ignored call button, unclear treatment plans
• Medium/Medium: Unhelpful admin staff
• Low/Low: Positive feedback about compassionate care

General Complaints

• High/High: Long wait times in emergency, incorrect billing charges
• Medium/Medium: Unclean rooms, non-working AC, prescription refill issues, food quality
• Low/Low: Parking issues, minor facility concerns

What Gets Created

For each complaint, the command creates:

1. Complaint Record:

   • Unique reference number (format: CMP-{hospital_code}-{year}-{UUID})
   • Title and description (bilingual)
   • Severity and priority
   • Category assignment
   • Hospital and department (linked to staff if applicable)
   • Patient name (bilingual)
   • Contact information (email/phone)
   • Source (patient, family, call_center, online, in_person)
   • Status: OPEN
   • Mentioned staff (if staff-mentioned complaint)

2. Timeline Entry:

   • Initial status change to 'open'
   • Description: "Complaint created and registered"
   • System-created (no user)

3. Automatic Processing (via Django signals):

   • SLA deadline calculation (based on severity/priority)
   • AI analysis (sentiment, categorization, etc.)
   • Assignment logic (if configured)
   • Notifications (if configured)

Example Output

============================================================
Complaint Data Seeding Command
============================================================

Found 2 hospital(s)

Configuration:
  Total complaints to create: 10
  Arabic complaints: 7 (70%)
  English complaints: 3 (30%)
  Staff-mentioned: 6 (60%)
  General: 4 (40%)
  Status: All OPEN
  Dry run: False

============================================================
Summary:
  Total complaints created: 10
  Arabic: 7
  English: 3
  Staff-mentioned: 6
  General: 4
============================================================

Complaint seeding completed successfully!

Testing SLA with Seeded Complaints

After seeding complaints, you can test the SLA system:

1. Check SLA Deadlines:

   python manage.py shell
   >>> from apps.complaints.models import Complaint
   >>> for c in Complaint.objects.all():
   ...     print(f"{c.reference}: {c.due_at}, Overdue: {c.is_overdue}")
   

2. Manually Trigger SLA Reminders:

   python manage.py shell
   >>> from apps.complaints.tasks import send_sla_reminders
   >>> send_sla_reminders()
   

3. Run SLA Functionality Tests:

   python test_sla_functionality.py
   

Troubleshooting

No Hospitals Found

ERROR: No active hospitals found. Please create hospitals first.

Solution: Run python manage.py seed_departments to create hospitals.

No Complaint Categories Found

ERROR: No complaint categories found. Please run seed_complaint_configs first.

Solution: Run python manage.py seed_complaint_configs to create categories.

No Staff Found

WARNING: No staff found. Staff-mentioned complaints will not have linked staff.

Solution: Run python manage.py seed_staff to create staff data (optional but recommended).

Import Errors

ModuleNotFoundError: No module named 'apps.complaints'

Solution: Ensure you're running the command from the project root directory.

Best Practices

1. Start Small: Test with 5-10 complaints first using --dry-run
2. Check Data: Verify complaints in Django Admin before running in production
3. Monitor AI Analysis: Check that AI analysis is being triggered via signals
4. Test SLA: Use seeded complaints to test SLA reminders and escalation
5. Clear Carefully: Use --clear option carefully as it deletes all existing complaints

Related Commands

• seed_complaint_configs - Creates SLA configs, categories, thresholds, escalation rules
• seed_staff - Creates staff data
• seed_departments - Creates hospital and department data
• test_sla_functionality - Tests SLA system

Support

For issues or questions:

1. Check the main documentation: docs/SLA_TESTING_PLAN.md
2. Review the code: apps/complaints/management/commands/seed_complaints.py
3. Check Django Admin to verify created data