HH/MULTIPLE_DEPARTMENTS_STAFF_IMPLEMENTATION.md

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.

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.

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

# 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 ✅