# 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
```python
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
```python
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
```python
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
```python
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
```python
def perform_create(self, serializer):
    # Auto-set created_by from request.user
    complaint = serializer.save(created_by=self.request.user)
```

#### InquiryViewSet perform_create
```python
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:**
```python
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:**
```python
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:**
```python
# 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