249 lines
6.7 KiB
Markdown
249 lines
6.7 KiB
Markdown
# 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** ✅
|