HH/docs/COMPLAINT_WORKFLOW_SIMPLIFICATION.md

# Complaint Workflow Simplification

## Overview

The complaint assignment workflow has been simplified to eliminate confusion between two types of assignments:
- **Case Manager** (User who manages the complaint)
- **Staff Member** (The person the complaint is about)

## Changes Made

### 1. Removed Case Manager Assignment

**Before:** Users could assign a "Case Manager" to complaints via a sidebar card.

**After:** This functionality has been completely removed.

### 2. Removed "Change Department" Quick Action

**Before:** PX Admins could change complaint department from the sidebar.

**After:** Department is now auto-set based on staff assignment and cannot be manually changed.

### 3. Simplified Assignment Sidebar

**Before:** Sidebar had two separate cards:
- "Staff Assignment" (for the person the complaint is about)
- "Assignment Info" (showing assigned_to - the case manager)

**After:** Only one card remains:
- "Staff Assignment" - Shows the staff member the complaint is about
- "Assignment Info" section remains but shows historical data (resolved_by, closed_by)

### 4. Auto-Set Department from Staff

When PX Admins assign staff to a complaint:
- The department is automatically set to the staff member's department
- This ensures consistency between staff and department
- No manual department changes needed

### 5. AI Shows Suggestions Only

**Before:** AI analysis would auto-assign staff to complaints.

**After:** AI now only provides suggestions:
- Staff matches are stored in metadata (`ai_analysis.staff_matches`)
- No automatic assignment occurs
- PX Admins must manually review and select from suggestions

## New Workflow

### Step 1: Complaint Created
- User creates a complaint
- AI analyzes and suggests:
  - Severity, priority, category
  - Department (if confidence >= 0.7)
  - Staff matches (with confidence scores)

### Step 2: PX Admin Review
- PX Admin opens complaint detail page
- Sees "Staff Assignment" card
- If staff not assigned:
  - Can see AI suggestions with confidence scores
  - Can click "Select" to assign a suggested staff
  - Can click "Search All Staff" to browse entire hospital staff list

### Step 3: Staff Assignment
- When staff is selected:
  - `complaint.staff` is set to selected staff
  - `complaint.department` is auto-set to staff's department
  - Timeline entry records the assignment

### Step 4: Complaint Management
- Assignee field (`assigned_to`) is used for:
  - SLA escalation (assigns to higher-level users)
  - Notification routing (who receives emails)
  - Historical tracking (resolved_by, closed_by)

## Benefits

1. **Clearer UI**: No confusion between two types of assignments
2. **Simpler Workflow**: One type of assignment - the staff member the complaint is about
3. **AI as Helper**: AI provides suggestions but doesn't make automatic decisions
4. **Consistent Data**: Department always matches staff department
5. **Better Control**: PX Admins have full control over staff assignment

## API Changes

### `/api/complaints/{id}/assign_staff/`

**Before:** 
```json
{
  "staff_id": "...",
  "reason": "..."
}
```

**After:**
```json
{
  "staff_id": "...",
  "reason": "..."
}
// Response includes auto-assigned department
{
  "message": "Staff assigned successfully",
  "staff_id": "...",
  "staff_name": "...",
  "department_id": "...",  // Auto-set
  "department_name": "..."
}
```

## Template Changes

### Removed from `complaint_detail.html`:

```html
<!-- Removed: Case Manager Assignment Card -->
<div class="card">
  <div class="card-header">
    <h6>Assign Case Manager</h6>
  </div>
  <div class="card-body">
    <!-- Assignment form removed -->
  </div>
</div>

<!-- Removed: Change Department Quick Action -->
<form method="post" action="{% url 'complaints:complaint_change_department' complaint.id %}">
  <!-- Department change form removed -->
</form>
```

### Updated in `complaint_detail.html`:

```html
<!-- Simplified: Staff Assignment Only -->
<div class="card">
  <div class="card-header bg-info text-white">
    <h6><i class="bi bi-person-badge"></i> Staff Assignment</h6>
  </div>
  <div class="card-body">
    <label>Staff Member</label>
    <small>Staff member that complaint is about</small>
    
    {% if complaint.staff %}
      <div class="alert alert-info">
        <i class="bi bi-person-check"></i>
        {{ complaint.staff.get_full_name }}
        <button data-bs-toggle="modal" data-bs-target="#staffSelectionModal">
          <i class="bi bi-pencil"></i>
        </button>
      </div>
    {% else %}
      <button data-bs-toggle="modal" data-bs-target="#staffSelectionModal">
        <i class="bi bi-person-plus"></i> Assign Staff
      </button>
    {% endif %}
  </div>
</div>
```

## Task Changes

### `analyze_complaint_with_ai` Task

**Before:**
```python
# Auto-assign staff if confidence >= 0.6
if staff_confidence >= 0.6:
    complaint.staff = staff  # Auto-assigned!
```

**After:**
```python
# Only store suggestions in metadata
# DO NOT AUTO-ASSIGN - PX Admins will manually select
logger.info(
    f"Found staff suggestion: {best_match['name_en']} "
    f"NOT auto-assigned, pending manual review"
)

# Only assign department if confidence is high enough
if staff_confidence >= 0.7:
    complaint.department = dept
```

## Migration Notes

### Existing Data

No database migration is required. The changes are:

1. **Code-level**: Template updates, task logic changes
2. **UI-level**: Removed assignment forms
3. **API-level**: Auto-set department on staff assignment

Existing complaints will continue to work as before:
- `assigned_to` field remains (used for escalation/notifications)
- `staff` field remains (the person complaint is about)
- `department` field remains (will be updated when staff is assigned)

## Testing Checklist

- [ ] Create new complaint - verify AI doesn't auto-assign staff
- [ ] View complaint with AI suggestions - verify suggestions are displayed
- [ ] Assign staff from suggestions - verify department auto-sets
- [ ] Search and assign staff from full list - verify department auto-sets
- [ ] Verify no Case Manager assignment option exists
- [ ] Verify no "Change Department" quick action exists
- [ ] Verify sidebar only shows Staff Assignment card
- [ ] Test SLA escalation still works with assignee field
- [ ] Verify notification routing uses assignee field correctly

## Future Considerations

1. **Reintroduce Case Manager**: If needed, this can be added back with clearer labeling
2. **Department Override**: Add option to override auto-set department in edge cases
3. **Bulk Assignment**: Add ability to assign staff to multiple complaints
4. **Staff Unassignment**: Add ability to unassign staff if needed

## Related Documentation

- [SLA System Overview](SLA_SYSTEM_OVERVIEW.md)
- [Staff Hierarchy Integration](STAFF_HIERARCHY_INTEGRATION.md)
- [Complaints Implementation Status](COMPLAINTS_IMPLEMENTATION_STATUS.md)