HH/COMPLAINTS_GAP_ANALYSIS.md

# Complaints App - Gap Analysis & Improvement Plan

**Date:** December 25, 2025  
**Analyst:** AI Assistant  
**Status:** Ready for Implementation

---

## Executive Summary

The complaints app has a solid foundation with core CRUD operations, SLA tracking, and UI templates. However, several critical features from the initial prompt are missing or incomplete. This document outlines the gaps and provides a systematic implementation plan.

---

## Current Implementation Status

### ✅ What's Working Well

1. **Models**
   - ✅ Complaint model with comprehensive fields
   - ✅ ComplaintAttachment for file uploads
   - ✅ ComplaintUpdate for timeline tracking
   - ✅ Inquiry model for non-complaint requests
   - ✅ SLA due_at calculation on creation
   - ✅ Overdue checking mechanism

2. **API Views (DRF)**
   - ✅ ComplaintViewSet with RBAC filtering
   - ✅ Custom actions: assign, change_status, add_note
   - ✅ ComplaintAttachmentViewSet
   - ✅ InquiryViewSet with respond action
   - ✅ Audit logging integration

3. **UI Views**
   - ✅ Complaint list with advanced filters
   - ✅ Complaint detail with tabs (details, timeline, attachments, actions)
   - ✅ Complaint create form
   - ✅ Action handlers: assign, change_status, add_note, escalate
   - ✅ RBAC enforcement

4. **Templates**
   - ✅ Modern Bootstrap 5 UI
   - ✅ Responsive design
   - ✅ Filter panel with collapsible functionality
   - ✅ Statistics cards
   - ✅ Timeline visualization
   - ✅ Status and severity badges

5. **Celery Tasks**
   - ✅ check_overdue_complaints (periodic)
   - ✅ send_complaint_resolution_survey (triggered on close)
   - ✅ create_action_from_complaint (stub for Phase 6)

---

## 🔴 Critical Gaps Identified

### 1. Configuration Models Missing

**Current State:** SLA durations are hardcoded in settings.py  
**Required:** Database-driven configuration per hospital/severity

**Missing Models:**
- `ComplaintSLAConfig` - Configure SLA hours by hospital, severity, priority
- `ComplaintCategory` - Custom categories per hospital (not hardcoded choices)
- `EscalationRule` - Define escalation hierarchy (flexible, not hardcoded)
- `ComplaintThreshold` - Configure thresholds (e.g., resolution survey score < 50%)

**Impact:** Cannot customize SLA rules, categories, or escalation per hospital

---

### 2. Resolution Satisfaction Survey Workflow Incomplete

**Current State:**
- ✅ Survey is sent when complaint closes
- ❌ No automatic detection of low scores
- ❌ No automatic PX Action creation on low scores
- ❌ No threshold configuration

**Required:**
- Detect when resolution survey score < 50% (configurable threshold)
- Automatically create PX Action when threshold breached
- Link PX Action to both complaint and survey
- Audit log the trigger

**Impact:** Manual intervention required for negative satisfaction scores

---

### 3. Complaint-to-PXAction Automation Missing

**Current State:**
- Task stub exists: `create_action_from_complaint`
- Not implemented
- Not triggered on complaint creation

**Required:**
- Automatic PX Action creation on complaint creation (if configured)
- Automatic PX Action creation on negative resolution survey
- Configuration per hospital: auto_create_action_on_complaint (boolean)
- Proper linking via GenericForeignKey

**Impact:** PX Actions must be created manually

---

### 4. Export Functionality Not Implemented

**Current State:**
- ✅ UI has export buttons (CSV, Excel)
- ❌ No backend implementation
- ❌ exportData() JavaScript function does nothing

**Required:**
- CSV export with all complaint fields
- Excel export with formatting
- PDF export for individual complaint (detail view)
- Respect current filters when exporting
- Include related data (patient, hospital, timeline)

**Impact:** Users cannot export data for reporting

---

### 5. Bulk Actions Not Implemented

**Current State:**
- ✅ UI has checkboxes for selection
- ✅ "Select All" functionality
- ❌ No bulk action handlers

**Required:**
- Bulk assign to user
- Bulk status change
- Bulk escalate
- Bulk export selected
- Confirmation modals for destructive actions

**Impact:** Users must process complaints one by one

---

### 6. Dashboard Integration Missing

**Current State:**
- ❌ No complaint metrics in command center dashboard
- ❌ No complaint trends visualization
- ❌ No SLA compliance tracking
- ❌ No resolution rate metrics

**Required (in dashboard app):**
- Complaint trends chart (daily/weekly/monthly)
- SLA compliance percentage and trend
- Resolution rate by hospital/department
- Average resolution time
- Top complaint categories
- Overdue complaints widget
- Recent high-severity complaints feed

**Impact:** No executive visibility into complaint performance

---

### 7. Escalation Logic Incomplete

**Current State:**
- ✅ Manual escalation via UI
- ✅ escalated_at timestamp recorded
- ❌ No automatic escalation on SLA breach
- ❌ No configurable escalation rules
- ❌ No escalation hierarchy

**Required:**
- Automatic escalation when overdue
- Configurable escalation rules per hospital
- Escalation hierarchy: Assigned User → Dept Manager → Hospital Admin → PX Admin
- Notification on escalation
- Audit trail

**Impact:** Overdue complaints don't automatically escalate

---

### 8. Complaint Categories Hardcoded

**Current State:**
- Categories are hardcoded in model choices
- Cannot add/edit/delete categories
- Same categories for all hospitals

**Required:**
- ComplaintCategory model
- CRUD UI for managing categories
- Per-hospital categories
- Active/inactive status
- Subcategories support

**Impact:** Cannot customize categories per hospital needs

---

### 9. Notification Integration Incomplete

**Current State:**
- ✅ Resolution survey sends notification
- ❌ No notifications for: complaint created, assigned, overdue, escalated

**Required:**
- Notification on complaint creation (to assigned user/dept manager)
- Notification on assignment (to assignee)
- Notification on overdue (to assignee + manager)
- Notification on escalation (to escalation target)
- Notification on resolution (to patient)
- Configurable notification preferences

**Impact:** Users miss important complaint events

---

### 10. Advanced Features Missing

**Current State:** Basic CRUD implemented

**Missing from Prompt Requirements:**
- Saved filter views (user can save frequently used filters)
- Complaint resolution satisfaction dashboard
- Dissatisfied complaints list with drill-down
- Evidence attachment requirements (before closure)
- Approval workflow for closure (if configured)
- Integration with journey stages (link complaint to journey stage)
- MOH/CHI complaint reporting

**Impact:** Missing advanced workflow and reporting capabilities

---

## 📋 Systematic Implementation Plan

### Phase 1: Configuration Models & Admin (Priority: CRITICAL)

**Deliverables:**
1. Create `ComplaintSLAConfig` model
   - Fields: hospital, severity, priority, sla_hours, is_active
   - Admin interface
   - Migration
   - Update `Complaint.calculate_sla_due_date()` to use DB config

2. Create `ComplaintCategory` model
   - Fields: hospital, name_en, name_ar, code, parent (self-FK), is_active, order
   - Admin interface
   - Migration
   - Update Complaint model to use FK instead of choices
   - Data migration to convert existing categories

3. Create `EscalationRule` model
   - Fields: hospital, from_role, to_role, trigger_condition, order, is_active
   - Admin interface
   - Migration

4. Create `ComplaintThreshold` model
   - Fields: hospital, threshold_type, threshold_value, action_type, is_active
   - Admin interface
   - Migration
   - Default: resolution_survey_score < 50 → create_px_action

**Acceptance Criteria:**
- ✅ All models created with migrations
- ✅ Admin interfaces functional
- ✅ SLA calculation uses DB config
- ✅ Categories are dynamic
- ✅ Default configurations seeded

**Estimated Effort:** 4-6 hours

---

### Phase 2: Resolution Survey Integration (Priority: HIGH)

**Deliverables:**
1. Create signal handler in surveys app
   - Listen for SurveyInstance score update
   - Check if linked to complaint (via metadata)
   - Check threshold from ComplaintThreshold
   - Trigger PX Action creation if threshold breached

2. Update `send_complaint_resolution_survey` task
   - Store complaint_id in survey metadata
   - Create proper linkage

3. Create `create_px_action_from_survey` task
   - Create PXAction with proper fields
   - Link to both complaint and survey
   - Set priority based on score severity
   - Audit log

4. Update complaint detail UI
   - Show resolution survey score prominently
   - Show linked PX Action if created
   - Visual indicator for low scores

**Acceptance Criteria:**
- ✅ Survey completion triggers threshold check
- ✅ Low score (<50%) creates PX Action automatically
- ✅ PX Action properly linked
- ✅ Audit trail complete
- ✅ UI shows linkage

**Estimated Effort:** 3-4 hours

---

### Phase 3: Complaint-to-PXAction Automation (Priority: HIGH)

**Deliverables:**
1. Add field to Hospital model (or create HospitalComplaintConfig)
   - auto_create_action_on_complaint (boolean)
   - default_action_priority
   - default_action_assignee_role

2. Implement `create_action_from_complaint` task
   - Check hospital configuration
   - Create PXAction if enabled
   - Set appropriate fields
   - Link via GenericForeignKey
   - Audit log

3. Update complaint creation views
   - Trigger task after complaint created
   - Both API and UI views

4. Add configuration UI
   - Hospital admin can toggle auto-creation
   - Set default priority/assignee

**Acceptance Criteria:**
- ✅ Complaint creation triggers PX Action (if configured)
- ✅ Configuration per hospital works
- ✅ PX Action properly linked
- ✅ Can be disabled per hospital

**Estimated Effort:** 2-3 hours

---

### Phase 4: Export Functionality (Priority: MEDIUM)

**Deliverables:**
1. Create export utility functions
   - `export_complaints_csv(queryset, filters)`
   - `export_complaints_excel(queryset, filters)`
   - `export_complaint_pdf(complaint_id)`

2. Add export views
   - `/complaints/export/csv/`
   - `/complaints/export/excel/`
   - `/complaints/<id>/export/pdf/`

3. Update UI
   - Wire export buttons to proper endpoints
   - Add loading indicators
   - Handle errors gracefully

4. Libraries needed
   - csv (built-in)
   - openpyxl (Excel)
   - reportlab or weasyprint (PDF)

**Acceptance Criteria:**
- ✅ CSV export works with all fields
- ✅ Excel export has formatting
- ✅ PDF export for single complaint
- ✅ Exports respect filters
- ✅ File downloads properly

**Estimated Effort:** 3-4 hours

---

### Phase 5: Bulk Actions (Priority: MEDIUM)

**Deliverables:**
1. Create bulk action views
   - `bulk_assign_complaints`
   - `bulk_change_status`
   - `bulk_escalate`

2. Add JavaScript for bulk operations
   - Collect selected IDs
   - Show confirmation modal
   - Submit to bulk endpoint
   - Show results/errors

3. Add bulk action UI
   - Toolbar with bulk action buttons
   - Enabled only when items selected
   - Confirmation modals

4. Add bulk action endpoints to API
   - POST `/api/complaints/bulk-assign/`
   - POST `/api/complaints/bulk-status/`
   - POST `/api/complaints/bulk-escalate/`

**Acceptance Criteria:**
- ✅ Can select multiple complaints
- ✅ Bulk assign works
- ✅ Bulk status change works
- ✅ Bulk escalate works
- ✅ Confirmation required
- ✅ Results shown to user
- ✅ Audit logs created

**Estimated Effort:** 3-4 hours

---

### Phase 6: Dashboard Integration (Priority: HIGH)

**Deliverables:**
1. Create complaint analytics service
   - `get_complaint_trends(hospital, date_range)`
   - `get_sla_compliance(hospital, date_range)`
   - `get_resolution_rate(hospital, date_range)`
   - `get_top_categories(hospital, date_range)`
   - `get_overdue_complaints(hospital)`

2. Update dashboard views
   - Add complaint metrics to command center
   - Create dedicated complaints dashboard

3. Add charts to command center template
   - Complaint trends line chart
   - SLA compliance gauge
   - Resolution rate by department
   - Top categories bar chart
   - Overdue complaints table widget

4. Add API endpoints
   - `/api/analytics/complaints/trends/`
   - `/api/analytics/complaints/sla-compliance/`
   - `/api/analytics/complaints/resolution-rate/`

**Acceptance Criteria:**
- ✅ Command center shows complaint metrics
- ✅ Charts are interactive
- ✅ Data updates in real-time
- ✅ RBAC filters apply
- ✅ Date range filters work

**Estimated Effort:** 4-5 hours

---

### Phase 7: Escalation Automation (Priority: HIGH)

**Deliverables:**
1. Update `check_overdue_complaints` task
   - When complaint overdue, trigger escalation
   - Use EscalationRule to determine target
   - Create ComplaintUpdate entry
   - Send notification
   - Audit log

2. Create `escalate_complaint` task
   - Get escalation rules for hospital
   - Find next escalation target
   - Reassign complaint
   - Update escalated_at
   - Notify all parties

3. Add escalation history to UI
   - Show escalation chain in timeline
   - Visual indicator for escalated complaints

**Acceptance Criteria:**
- ✅ Overdue complaints auto-escalate
- ✅ Escalation follows configured rules
- ✅ Notifications sent
- ✅ Audit trail complete
- ✅ UI shows escalation history

**Estimated Effort:** 3-4 hours

---

### Phase 8: Category Management UI (Priority: MEDIUM)

**Deliverables:**
1. Create category CRUD views
   - List categories
   - Create category
   - Edit category
   - Delete/deactivate category
   - Reorder categories

2. Create category templates
   - `complaint_category_list.html`
   - `complaint_category_form.html`

3. Add to admin menu
   - "Complaint Categories" under Settings

4. Update complaint form
   - Dynamic category dropdown
   - Load from database
   - Filter by hospital

**Acceptance Criteria:**
- ✅ Can manage categories via UI
- ✅ Categories are per-hospital
- ✅ Subcategories supported
- ✅ Complaint form uses dynamic categories
- ✅ Inactive categories hidden

**Estimated Effort:** 2-3 hours

---

### Phase 9: Enhanced Notifications (Priority: MEDIUM)

**Deliverables:**
1. Create notification triggers
   - On complaint created
   - On complaint assigned
   - On complaint overdue
   - On complaint escalated
   - On complaint resolved
   - On complaint closed

2. Update views and tasks
   - Add notification calls
   - Use NotificationService

3. Add notification preferences
   - User can configure which notifications to receive
   - Per-event preferences

**Acceptance Criteria:**
- ✅ All events trigger notifications
- ✅ Notifications sent via configured channels
- ✅ Users can configure preferences
- ✅ Notification logs created

**Estimated Effort:** 2-3 hours

---

### Phase 10: Advanced Features (Priority: LOW)

**Deliverables:**
1. Saved filter views
   - SavedComplaintFilter model
   - Save current filters
   - Load saved filters
   - Share filters with team

2. Resolution satisfaction dashboard
   - Dedicated page
   - Score distribution
   - Dissatisfied list
   - Drill-down by hospital/department

3. Evidence requirements
   - Configure required attachments before closure
   - Validation on status change

4. Approval workflow
   - Require PX Admin approval for closure (if configured)
   - Approval queue

**Acceptance Criteria:**
- ✅ Users can save/load filters
- ✅ Resolution dashboard functional
- ✅ Evidence requirements enforced
- ✅ Approval workflow works

**Estimated Effort:** 6-8 hours

---

## 🎯 Implementation Priority Matrix

| Phase | Priority | Effort | Impact | Dependencies |
|-------|----------|--------|--------|--------------|
| 1. Configuration Models | CRITICAL | 4-6h | HIGH | None |
| 2. Resolution Survey Integration | HIGH | 3-4h | HIGH | Phase 1 |
| 3. Complaint-to-PXAction | HIGH | 2-3h | HIGH | Phase 1 |
| 6. Dashboard Integration | HIGH | 4-5h | HIGH | None |
| 7. Escalation Automation | HIGH | 3-4h | MEDIUM | Phase 1 |
| 4. Export Functionality | MEDIUM | 3-4h | MEDIUM | None |
| 5. Bulk Actions | MEDIUM | 3-4h | MEDIUM | None |
| 8. Category Management | MEDIUM | 2-3h | MEDIUM | Phase 1 |
| 9. Enhanced Notifications | MEDIUM | 2-3h | LOW | None |
| 10. Advanced Features | LOW | 6-8h | LOW | Multiple |

**Total Estimated Effort:** 33-46 hours

---

## 📊 Comparison with Initial Prompt

### Prompt Requirements vs Current Implementation

| Requirement | Status | Notes |
|-------------|--------|-------|
| Complaint CRUD | ✅ Complete | Models, API, UI all working |
| SLA tracking | ⚠️ Partial | Works but hardcoded, needs DB config |
| Workflow (open→progress→resolved→closed) | ✅ Complete | Status transitions working |
| Resolution satisfaction survey | ⚠️ Partial | Sends survey but no auto-action on low score |
| Low score triggers PX Action | ❌ Missing | Not implemented |
| Complaint SLA config | ❌ Missing | Hardcoded in settings |
| Escalation on overdue | ⚠️ Partial | Manual only, no auto-escalation |
| Timeline/audit trail | ✅ Complete | ComplaintUpdate tracks all changes |
| Attachments | ✅ Complete | File upload working |
| RBAC enforcement | ✅ Complete | Proper filtering by role |
| API endpoints | ✅ Complete | DRF viewsets with actions |
| Modern UI | ✅ Complete | Bootstrap 5, responsive |
| Advanced filters | ✅ Complete | Comprehensive filter panel |
| Export capability | ❌ Missing | UI exists but no backend |
| Bulk actions | ❌ Missing | UI exists but no backend |
| Dashboard integration | ❌ Missing | No complaint metrics in dashboard |
| Custom categories | ❌ Missing | Hardcoded choices |
| Configurable thresholds | ❌ Missing | No threshold model |

**Completion Score: 60%**

---

## 🚀 Quick Start Recommendations

### Immediate Actions (Next 2-3 days)

1. **Day 1: Configuration Foundation**
   - Implement Phase 1 (Configuration Models)
   - This unblocks multiple other phases
   - Critical for production readiness

2. **Day 2: Automation & Integration**
   - Implement Phase 2 (Resolution Survey Integration)
   - Implement Phase 3 (Complaint-to-PXAction)
   - Complete the core workflow

3. **Day 3: Visibility & Reporting**
   - Implement Phase 6 (Dashboard Integration)
   - Implement Phase 4 (Export Functionality)
   - Give users visibility into complaint performance

### Week 2 Actions

4. **Days 4-5: Operational Efficiency**
   - Implement Phase 5 (Bulk Actions)
   - Implement Phase 7 (Escalation Automation)
   - Improve user productivity

5. **Days 6-7: Polish & Enhancement**
   - Implement Phase 8 (Category Management)
   - Implement Phase 9 (Enhanced Notifications)
   - Improve user experience

---

## 📝 Technical Debt & Considerations

### Current Technical Debt

1. **Hardcoded Values**
   - SLA durations in settings.py
   - Complaint categories in model choices
   - Escalation logic not configurable

2. **Incomplete Workflows**
   - Resolution survey doesn't trigger actions
   - No automatic escalation
   - Manual PX Action creation

3. **Missing Integrations**
   - Dashboard doesn't show complaint metrics
   - Limited notification coverage
   - No export functionality

### Architectural Considerations

1. **Scalability**
   - Current implementation handles single-hospital well
   - Multi-hospital filtering works
   - Consider caching for dashboard metrics

2. **Performance**
   - Add database indexes for common filters
   - Use select_related/prefetch_related (already done)
   - Consider pagination for large datasets (already done)

3. **Maintainability**
   - Good separation of concerns
   - Clear model structure
   - Well-documented code

---

## 🎓 Knowledge Enrichment Summary

### What I Learned from Your Answers

1. **Threshold Configuration**
   - Start with 50% threshold for resolution satisfaction
   - Make it configurable in database for future flexibility
   - Different hospitals may have different standards

2. **SLA Configuration**
   - Must be database-driven, not hardcoded
   - Per hospital, per severity configuration needed
   - Allows business users to adjust without code changes

3. **PX Action Triggers**
   - Both on complaint creation AND negative survey
   - Dual trigger points ensure nothing falls through cracks
   - Configuration per hospital for flexibility

4. **Export Requirements**
   - CSV, Excel, and PDF all needed
   - Critical for reporting and compliance
   - Must respect current filters

5. **Bulk Operations**
   - Assign, escalate, status update are priorities
   - Improves operational efficiency
   - Reduces repetitive work

6. **Dashboard Integration**
   - All dashboard features go in dashboard app
   - Complaint trends, resolution rate, SLA compliance needed
   - Executive visibility is critical

7. **Escalation Flexibility**
   - Start with Department Manager
   - Must be configurable for different org structures
   - Escalation rules should be data-driven

8. **Survey Template Strategy**
   - Each hospital has own resolution satisfaction template
   - Questions can be added per journey stage
   - All questions sent at journey end
   - Flexible, hospital-specific approach

9. **Category Customization**
   - Categories must be custom per hospital
   - Users need CRUD operations on categories
   - Not one-size-fits-all

### Key Insights

- **Flexibility is paramount** - Everything should be configurable
- **Automation is critical** - Reduce manual work through smart triggers
- **Visibility matters** - Dashboard integration is high priority
- **User empowerment** - Give users control over configuration
- **Systematic approach** - Implement in logical sequence

---

## ✅ Next Steps

1. **Review this document** with stakeholders
2. **Prioritize phases** based on business needs
3. **Begin Phase 1** (Configuration Models) immediately
4. **Set up tracking** for implementation progress
5. **Schedule reviews** after each phase completion

---

## 📞 Questions for Further Clarification

1. **MOH/CHI Integration**: Should complaints be reportable to MOH/CHI? What format?
2. **Multi-language**: Should complaint forms support Arabic input?
3. **Patient Portal**: Can patients submit complaints directly via portal?
4. **Anonymous Complaints**: Should system support anonymous complaints?
5. **Complaint Merging**: Should duplicate complaints be mergeable?
6. **Complaint Reopening**: Can closed complaints be reopened?
7. **SLA Pause**: Should SLA timer pause when waiting for external input?
8. **Complaint Routing**: Should complaints auto-route based on category/department?

---

**Document Version:** 1.0  
**Last Updated:** December 25, 2025  
**Status:** Ready for Implementation