# Multiple Departments and Staff per Complaint - Implementation Summary

**Date:** February 16, 2026  
**Status:** ✅ Complete

---

## Overview

The complaint management system now supports **multiple departments and staff members** per complaint. This allows for complex complaints that involve multiple departments and various staff members with different roles.

---

## 🗄️ New Database Models

### 1. ComplaintInvolvedDepartment

Tracks departments involved in a complaint with specific roles.

```python
Fields:
- complaint: ForeignKey to Complaint
- department: ForeignKey to Department
- role: ChoiceField (primary, secondary, coordination, investigating)
- is_primary: Boolean (only one primary department per complaint)
- assigned_to: User assigned from this department
- assigned_at: Timestamp of assignment
- response_submitted: Boolean
- response_submitted_at: Timestamp
- response_notes: Text field for department response
- notes: General notes
- added_by: User who added this department
```

**Features:**
- Only one department can be marked as `is_primary` per complaint
- Automatic clearing of primary flag when new primary is set
- Response tracking per department
- Assignment tracking

### 2. ComplaintInvolvedStaff

Tracks staff members involved in a complaint with specific roles.

```python
Fields:
- complaint: ForeignKey to Complaint
- staff: ForeignKey to Staff
- role: ChoiceField (accused, witness, responsible, investigator, support, coordinator)
- explanation_requested: Boolean
- explanation_requested_at: Timestamp
- explanation_received: Boolean
- explanation_received_at: Timestamp
- explanation: Text field for staff explanation
- notes: General notes
- added_by: User who added this staff
```

**Features:**
- Multiple staff per complaint with different roles
- Explanation request and tracking
- Full audit trail

---

## 🔗 URL Routes

```python
# Involved Departments
/complaints/<uuid:complaint_pk>/departments/add/    # Add department
/complaints/departments/<uuid:pk>/edit/             # Edit department
/complaints/departments/<uuid:pk>/remove/           # Remove department
/complaints/departments/<uuid:pk>/response/         # Submit response

# Involved Staff
/complaints/<uuid:complaint_pk>/staff/add/          # Add staff
/complaints/staff/<uuid:pk>/edit/                   # Edit staff
/complaints/staff/<uuid:pk>/remove/                 # Remove staff
/complaints/staff/<uuid:pk>/explanation/            # Submit explanation
```

---

## 🎨 UI Components

### New Tabs in Complaint Detail

1. **Departments Tab** - Shows all involved departments
   - Primary department highlighted
   - Role badges
   - Assignment information
   - Response status
   - Add/Edit/Remove actions

2. **Staff Tab** - Shows all involved staff
   - Staff member details
   - Role badges
   - Explanation status
   - Add/Edit/Remove actions

### Forms

1. **ComplaintInvolvedDepartmentForm**
   - Department selection (filtered by hospital)
   - Role selection
   - Primary checkbox
   - Assignee selection
   - Notes

2. **ComplaintInvolvedStaffForm**
   - Staff selection (filtered by hospital)
   - Role selection
   - Notes

---

## 👥 Roles

### Department Roles

| Role | Description |
|------|-------------|
| **Primary** | Main responsible department for resolution |
| **Secondary** | Supporting/assisting the primary department |
| **Coordination** | Only for coordination purposes |
| **Investigating** | Leading the investigation |

### Staff Roles

| Role | Description |
|------|-------------|
| **Accused/Involved** | Staff member involved in the incident |
| **Witness** | Staff member who witnessed the incident |
| **Responsible** | Staff responsible for resolving the complaint |
| **Investigator** | Staff investigating the complaint |
| **Support** | Supporting the resolution process |
| **Coordinator** | Coordinating between departments |

---

## 🔐 Permissions

The `can_manage_complaint()` function now checks:

1. User is PX Admin
2. User is Hospital Admin for complaint's hospital
3. User is Department Manager for complaint's department
4. User is assigned to the complaint
5. **NEW:** User is assigned to one of the involved departments

---

## 📊 Admin Interface

New admin sections added:

- **ComplaintInvolvedDepartmentAdmin**
  - List view with filters
  - Edit view with all fields
  - Search by complaint, department

- **ComplaintInvolvedStaffAdmin**
  - List view with filters
  - Edit view with all fields
  - Search by complaint, staff name

- **Inlines in ComplaintAdmin**
  - Involved Departments inline
  - Involved Staff inline

---

## 🔄 Workflow Integration

### Adding a Department
1. User clicks "Add Department" in complaint detail
2. Selects department, role, optional assignee
3. System creates ComplaintInvolvedDepartment record
4. Audit log entry created
5. Complaint update logged

### Adding Staff
1. User clicks "Add Staff" in complaint detail
2. Selects staff member and role
3. System creates ComplaintInvolvedStaff record
4. Audit log entry created
5. Complaint update logged

### Department Response
1. Assigned user submits response
2. Response marked as submitted with timestamp
3. Available for review in complaint detail

### Staff Explanation
1. Staff member submits explanation
2. Explanation marked as received with timestamp
3. Available for review in complaint detail

---

## 📝 Migration

**File:** `apps/complaints/migrations/0015_add_involved_departments_and_staff.py`

**Creates:**
- `complaints_complaintinvolveddepartment` table
- `complaints_complaintinvolvedstaff` table
- Indexes for performance
- Unique constraints (complaint + department, complaint + staff)

---

## 🧪 Testing Checklist

- [ ] Add primary department to complaint
- [ ] Add secondary department to complaint
- [ ] Verify only one primary department allowed
- [ ] Add staff with different roles
- [ ] Submit department response
- [ ] Submit staff explanation
- [ ] Remove department/staff
- [ ] Check audit logs
- [ ] Check complaint timeline
- [ ] Verify permissions work correctly
- [ ] Test admin interface

---

## 🚀 Benefits

1. **Complex Complaints** - Handle complaints spanning multiple departments
2. **Clear Responsibilities** - Each department/staff has defined role
3. **Better Tracking** - Individual responses from each department
4. **Audit Trail** - Full history of who was involved when
5. **Escalation Support** - Can escalate to specific departments

---

## 📝 Notes

- The original `complaint.department` and `complaint.staff` fields remain for backward compatibility
- The new models provide extended functionality without breaking existing code
- All changes are audited via `AuditService`
- All activities are logged in the complaint timeline

---

**Implementation Complete** ✅