marwan/HH
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
HH/COMPLAINTS_GAP_ANALYSIS.md
Marwan Alwali edfd1cfe2e update complaints services
2025-12-25 17:11:40 +03:00

22 KiB
Raw Permalink Blame History

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

  1. Days 4-5: Operational Efficiency

    • Implement Phase 5 (Bulk Actions)
    • Implement Phase 7 (Escalation Automation)
    • Improve user productivity

  2. 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