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:

{
  "staff_id": "...",
  "reason": "..."
}

After:

{
  "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:

<!-- 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:

<!-- 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:

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

After:

# 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
• Staff Hierarchy Integration
• Complaints Implementation Status