# Collections Process Status Enhancement — Design

**Date:** 2026-02-22
**Status:** Approved
**File:** `admin/collections.cgi`

## Summary

Add a collections process tracking workflow to the Collections Manager. A new dropdown in the invoice detail panel lets dmoss update each invoice's status as he works through collections, with automated email notifications for key status changes (paid, delete request, send for review).

## Database Change

Single new column on `career_center.invoices`:

```sql
ALTER TABLE invoices ADD COLUMN collections_process_status
  ENUM('no_contact','pending_review','payment_arrangements','paid','delete_requested','sent_for_review')
  DEFAULT NULL;
```

No new tables. `employer_history` provides the audit trail via existing `logEvent()`.

## Status Options & Actions

| Status | DB Value | Action |
|--------|----------|--------|
| No contact made | `no_contact` | Updates status, logs event |
| Pending client review | `pending_review` | Updates status, logs event |
| Payment arrangements made | `payment_arrangements` | Updates status, logs event |
| Paid | `paid` | Sets `paid_date = CURDATE()`, emails wrmoss + dmoss + original sales rep |
| Delete invoice | `delete_requested` | Emails wrmoss for approval (does NOT delete), logs event |
| Send for review | `sent_for_review` | Prompts for justification, emails wrmoss + original sales rep |

## UI Changes

### Detail Panel (right side)

New "Collections Process Status" section at top of detail panel, below header and above action buttons:
- Dropdown with all 6 status options
- "Update Status" button
- Shows current status with badge
- "Send for review" shows a textarea for justification before submitting

### Search Filters

New dropdown in the filter row: `[All Process Status ▼]`
- Filters both "Active Collections" and "Available to Claim" tabs
- Options mirror the 6 statuses above

## Email Notifications

1. **Paid** → Full team (wrmoss, dmoss, split_commission rep): "Invoice #X collected — $Y,YYY.YY"
2. **Delete Request** → wrmoss: "dmoss requests deletion of Invoice #X — [justification]"
3. **Send for Review** → wrmoss + original sales rep: "Invoice #X sent for review — [justification]"

All emails use `html_notify()` with branded HBCU Connect template style.

## Files Modified

- `admin/collections.cgi` — new AJAX action, updated queries, updated JS
- Database — ALTER TABLE (one column)

## Backend Changes

- New AJAX action: `update_process_status`
- Updated `getQueue` / `getClaimable` to SELECT and filter by `collections_process_status`
- Updated `getInvoiceDetail` to include `collections_process_status`