HH/COMPLAINT_INQUIRY_CREATOR_TRACKING.md

Complaint & Inquiry Creator Tracking Implementation

Overview

This implementation adds complete creator tracking and data isolation for complaints and inquiries in the PX360 Patient Experience Software. The system now tracks WHO creates complaints and inquiries, and ensures proper data isolation based on user roles.

Implementation Summary

1. Database Changes ✅

Added created_by Field to Complaint Model

created_by = models.ForeignKey(
    'accounts.User',
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name='created_complaints',
    help_text="User who created this complaint (SourceUser or Patient)"
)

Added created_by Field to Inquiry Model

created_by = models.ForeignKey(
    'accounts.User',
    on_delete=models.SET_NULL,
    null=True,
    blank=True,
    related_name='created_inquiries',
    help_text="User who created this inquiry (SourceUser or Patient)"
)

Migration Applied

• File: apps/complaints/migrations/0004_complaint_created_by_inquiry_created_by_and_more.py
• Status: ✅ Applied successfully

---

2. Permission Classes ✅

Created apps/complaints/permissions.py

CanCreateComplaint Permission

• PX Admins can create complaints
• Hospital Admins can create complaints
• Source Users can create if they have can_create_complaints permission
• Patients can create their own complaints

CanCreateInquiry Permission

• PX Admins can create inquiries
• Hospital Admins can create inquiries
• Source Users can create if they have can_create_inquiries permission
• Patients can create their own inquiries

CanAccessOwnData Permission

• PX Admins can access all data
• Source Users can only access data they created
• Patients can only access their own data

---

3. Smart Data Isolation ✅

ComplaintViewSet Filtering

def get_queryset(self):
    # PX Admins see all complaints
    if user.is_px_admin():
        return queryset
    
    # Source Users see ONLY complaints THEY created
    if hasattr(user, 'source_user_profile') and user.source_user_profile.exists():
        return queryset.filter(created_by=user)
    
    # Patients see ONLY their own complaints
    if hasattr(user, 'patient_profile'):
        return queryset.filter(patient__user=user)
    
    # Hospital Admins see complaints for their hospital
    # Department Managers see complaints for their department
    # Others see complaints for their hospital

InquiryViewSet Filtering

def get_queryset(self):
    # Same filtering logic as ComplaintViewSet
    # Source Users see ONLY inquiries THEY created
    # Patients see ONLY their own inquiries
    # PX Admins see all inquiries

---

4. Serializer Updates ✅

ComplaintSerializer

• Added created_by field (read-only)
• Added created_by_name computed field (method)

InquirySerializer

• Added created_by field (read-only)
• Added created_by_name computed field (method)
• Added source field to fields list

---

5. Auto-Set Creator on Creation ✅

ComplaintViewSet perform_create

def perform_create(self, serializer):
    # Auto-set created_by from request.user
    complaint = serializer.save(created_by=self.request.user)

InquiryViewSet perform_create

def perform_create(self, serializer):
    # Auto-set created_by from request.user
    inquiry = serializer.save(created_by=self.request.user)

---

6. Admin Configuration ✅

ComplaintAdmin Updates

• Added created_by to list_display
• Added created_by to list_filter
• Added "Creator Tracking" fieldset
• Added created_by to queryset select_related

InquiryAdmin Updates

• Added created_by to list_display
• Added created_by to list_filter
• Added source to list_filter
• Added "Creator Tracking" fieldset
• Added created_by to queryset select_related

---

User Hierarchy & Workflow

User Types

1. PX Admin

   • Can see ALL complaints and inquiries
   • Full management capabilities
   • Can create any complaint/inquiry

2. Hospital Admin

   • Can see all complaints/inquiries for their hospital
   • Can manage hospital-level data
   • Can create complaints/inquiries

3. Department Manager

   • Can see complaints/inquiries for their department
   • Can manage department-level data

4. Source User (Call Center Agents, etc.)

   • Can create complaints/inquiries (with permission)
   • Can ONLY see complaints/inquiries THEY created
   • Perfect for call center isolation

5. Patient

   • Can create their own complaints/inquiries
   • Can ONLY see their own data

---

Data Isolation Matrix

User Type	Can See	Can Create
PX Admin	ALL data	Yes
Hospital Admin	Hospital data	Yes
Department Manager	Department data	No (via UI)
Source User John	ONLY John's created data	Yes (if has permission)
Patient Ahmed	ONLY Ahmed's data	Yes (own complaints)

---

Example Use Cases

Use Case 1: Call Center Agent Creates Complaint

Scenario:

• Agent John is a SourceUser linked to "Call Center" source
• Agent John receives a call from Patient Ahmed
• Agent John creates a complaint for Ahmed

Result:

complaint = Complaint.objects.create(
    patient=ahmed_patient,
    hospital=ahmed_hospital,
    title="Long wait time",
    description="Waited 3 hours",
    source=call_center_source,
    created_by=john_user  # <-- Auto-set from request.user
)

Data Access:

• Agent John sees ONLY complaints created by John
• Agent Sarah sees ONLY complaints created by Sarah
• PX Admin sees ALL complaints

---

Use Case 2: Patient Creates Own Complaint

Scenario:

• Patient Ahmed logs into patient portal
• Patient Ahmed creates a complaint

Result:

complaint = Complaint.objects.create(
    patient=ahmed_patient,
    hospital=ahmed_hospital,
    title="Billing issue",
    description="Incorrect charge",
    source=patient_portal_source,
    created_by=ahmed_user  # <-- Auto-set from request.user
)

Data Access:

• Patient Ahmed sees ONLY his own complaints
• Patients cannot see other patients' data
• PX Admin sees ALL complaints

---

Use Case 3: PX Admin Oversight

Scenario:

• PX Admin wants to view all complaints
• PX Admin needs to track performance per source/agent

Result:

# PX Admin sees all complaints
queryset = Complaint.objects.all()

# Can filter by creator
agent_john_complaints = queryset.filter(created_by=john_user)

# Can view audit trail
complaint = Complaint.objects.get(id=123)
print(complaint.created_by)  # Shows who created it
print(complaint.created_by_name)  # Shows creator's full name

---

Files Modified

Database Models

• apps/complaints/models.py - Added created_by fields

Migrations

• apps/complaints/migrations/0004_complaint_created_by_inquiry_created_by_and_more.py - New migration

Permissions

• apps/complaints/permissions.py - New permission classes

Views

• apps/complaints/views.py - Updated ViewSets with smart filtering and auto-set creator

Serializers

• apps/complaints/serializers.py - Updated serializers with creator fields

Admin

• apps/complaints/admin.py - Updated admin configuration

---

API Changes

Complaint API Endpoints

GET /api/complaints/

• Returns complaints filtered by user role
• Source Users see ONLY their created complaints
• Patients see ONLY their own complaints
• PX Admins see ALL complaints

POST /api/complaints/

• Creates new complaint
• Auto-sets created_by from authenticated user
• Requires appropriate permissions

GET /api/complaints/{id}/

• Returns single complaint
• Enforces object-level permissions

Inquiry API Endpoints

GET /api/inquiries/

• Returns inquiries filtered by user role
• Source Users see ONLY their created inquiries
• Patients see ONLY their own inquiries
• PX Admins see ALL inquiries

POST /api/inquiries/

• Creates new inquiry
• Auto-sets created_by from authenticated user
• Requires appropriate permissions

---

Admin Changes

Complaint List View

• Added "Created By" column
• Added "Created By" filter
• Can see who created each complaint

Inquiry List View

• Added "Created By" column
• Added "Created By" filter
• Added "Source" filter
• Can see who created each inquiry

Detail Views

• Added "Creator Tracking" fieldset
• Shows creator information in admin panel

---

Testing Checklist

Test Case 1: Source User Creates Complaint

• Login as Source User
• Create a complaint
• Verify created_by is set correctly
• Verify complaint appears in list
• Verify complaint NOT visible to other Source Users
• Verify complaint IS visible to PX Admin

Test Case 2: Patient Creates Complaint

• Login as Patient
• Create a complaint
• Verify created_by is set correctly
• Verify complaint appears in list
• Verify complaint NOT visible to other patients
• Verify complaint IS visible to PX Admin

Test Case 3: Data Isolation

• Create complaint as Source User A
• Create complaint as Source User B
• Login as Source User A
• Verify ONLY Source User A's complaints visible
• Login as Source User B
• Verify ONLY Source User B's complaints visible
• Login as PX Admin
• Verify ALL complaints visible

Test Case 4: Admin Filtering

• Login as PX Admin
• Navigate to Complaint List
• Filter by "Created By"
• Verify filtering works correctly

---

Security Considerations

Data Isolation

• ✅ Source Users cannot see other Source Users' data
• ✅ Patients cannot see other patients' data
• ✅ Object-level permissions enforced in views
• ✅ Queryset filtering prevents unauthorized access

Audit Trail

• ✅ Every complaint/inquiry has created_by field
• ✅ Audit logs include creator information
• ✅ Admin panel shows creator history

Null Safety

• ✅ created_by can be NULL (for legacy data or anonymous submissions)
• ✅ Proper handling in serializers and views

---

Future Enhancements

Potential Improvements

1. Anonymous Submission Tracking

   • Add created_by_type enum (user, anonymous, system)
   • Track anonymous submissions with session/cookie

2. Creator Statistics Dashboard

   • Show complaints created per Source User
   • Track performance metrics
   • Compare agent productivity

3. Bulk Assignment

   • Allow PX Admins to reassign complaints between agents
   • Track assignment history

4. Multi-Source Tracking

   • Track when a complaint is moved between sources
   • Maintain source transition history

---

Summary

This implementation provides:

• ✅ Complete creator tracking for complaints and inquiries
• ✅ Smart data isolation based on user roles
• ✅ Permission-based access control
• ✅ Auto-set creator on creation
• ✅ Admin panel updates for visibility
• ✅ API endpoint filtering
• ✅ Audit trail compliance

The system now properly tracks who creates each complaint and inquiry, ensuring:

• Call Center Agents only see their own created complaints
• Patients only see their own complaints
• PX Admins maintain full oversight
• Clear audit trail for compliance

---

Implementation Date: January 12, 2026 Status: ✅ Complete and Deployed