Referral Status Update Implementation - Testing Guide

What Was Implemented

1. API Route: /api/referrals/[id]/update-status

• Location: app/api/referrals/[id]/update-status/route.ts
• Method: POST
• Features:
  • Validates status values
  • Checks user authentication
  • Verifies permissions (admin, caseworker org, or provider org)
  • Updates referral status and timestamps
  • Creates activity log entries
  • Returns success/error responses

2. Client Component: ReferralStatusButtons

• Location: app/components/ReferralStatusButtons.tsx
• Features:
  • Four status update buttons: In Review, Accept, Deny, Complete
  • Loading states during API calls
  • Success/error message display
  • Disables buttons for current status
  • Auto-refreshes page data after successful update

3. Integration

• Location: app/(crm)/referrals/[id]/page.tsx
• Replaced static buttons with interactive ReferralStatusButtons component
• Maintains existing permission logic (canUpdateStatus)

Permissions

Users can update referral status if they are:

1. Admin - Can update any referral
2. Caseworker Organization - Members of the organization that created the referral
3. Provider Organization - Members of the organization that owns the resource

Status Workflow

Available statuses:

• draft - Initial state
• submitted - Referral submitted
• in_review - Provider reviewing
• accepted - Provider accepted referral
• denied - Provider denied referral
• completed - Service completed
• cancelled - Referral cancelled

How to Test

Prerequisites

1. Ensure your database has the Resource Library migration applied
2. Have at least one test organization, resource, household, and referral
3. Have a user account with appropriate permissions

Step 1: Create Test Data (if not already done)

-- Create organization
INSERT INTO organizations (name, org_type, city, state)
VALUES ('Test Provider', 'service_provider', 'Medford', 'Oregon');

-- Link your user to the organization
UPDATE profiles 
SET org_id = (SELECT id FROM organizations WHERE name = 'Test Provider'),
    role = 'org_admin'
WHERE email = 'your-email@example.com';

Step 2: Login and Navigate

1. Go to http://localhost:3000/crm/login
2. Login with your credentials
3. Navigate to /referrals
4. Click on any referral to view details

Step 3: Test Status Updates

On the referral detail page, you should see the "Update Status" section with four buttons:

1. Test "Mark as In Review"

   • Click the button
   • Button should show "Updating..." while processing
   • Success message should appear
   • Page should refresh
   • Status badge at top should update to "in_review"
   • Activity timeline should show new status change entry

2. Test "Accept Referral"

   • Click the "Accept Referral" button
   • Verify same success flow as above
   • Status should change to "accepted"

3. Test "Deny Referral"

   • Click the "Deny Referral" button
   • Status should change to "denied"

4. Test "Mark as Completed"

   • Click the "Mark as Completed" button
   • Status should change to "completed"

Step 4: Verify Database Changes

After each status update, check the database:

-- Verify referral was updated
SELECT id, status, status_updated_at, status_updated_by 
FROM referrals 
WHERE id = 'your-referral-id';

-- Verify activity log was created
SELECT * 
FROM referral_activities 
WHERE referral_id = 'your-referral-id' 
ORDER BY created_at DESC;

Step 5: Test Permission Restrictions

1. Test with different user types:

   • Login as an admin → Should see buttons
   • Login as caseworker from same org → Should see buttons
   • Login as provider org member → Should see buttons
   • Login as user from different org → Should NOT see buttons

2. Test disabled states:

   • When a referral is already "accepted", the "Accept Referral" button should be disabled
   • Same for other statuses

Step 6: Test Error Scenarios

1. Invalid status (via API directly):

   curl -X POST http://localhost:3000/api/referrals/[id]/update-status \
     -H "Content-Type: application/json" \
     -d '{"status":"invalid_status"}'
   

   Should return 400 error

2. Unauthorized access:

   • Try accessing referral from organization you don't belong to
   • Should return 403 error

3. Nonexistent referral:

   • Try updating a fake UUID
   • Should return 404 error

Expected Behavior

Success Flow

1. User clicks button
2. Button shows "Updating..." text
3. Button is disabled
4. API call is made
5. Success message appears in green box
6. Page refreshes automatically
7. Updated status appears in status badge
8. New activity appears in timeline
9. Current status text updates at bottom

Error Flow

1. User clicks button
2. Button shows "Updating..."
3. API returns error
4. Red error message box appears
5. Button re-enables
6. User can retry

Troubleshooting

Buttons Don't Appear

• Check user has correct permissions
• Verify canUpdateStatus evaluates to true
• Check browser console for errors

Status Doesn't Update

• Check browser Network tab for API errors
• Verify database RLS policies allow the update
• Check server logs for error messages

Activity Log Not Created

• Check if referral_activities table exists
• Verify user permissions on that table
• Activity log errors don't fail the request

API Response Examples

Success

{
  "success": true,
  "message": "Status updated successfully"
}

Error - Unauthorized

{
  "error": "Unauthorized - not logged in"
}

Error - Forbidden

{
  "error": "Forbidden - insufficient permissions"
}

Error - Invalid Status

{
  "error": "Invalid status"
}

Files Modified

1. ✅ app/api/referrals/[id]/update-status/route.ts (created)
2. ✅ app/components/ReferralStatusButtons.tsx (created)
3. ✅ app/(crm)/referrals/[id]/page.tsx (modified)

Next Steps (Future Enhancements)

1. Add Confirmation Dialogs: Especially for "Deny" and "Completed"
2. Add Notes Field: Allow users to add notes when updating status
3. Add Denial Reason: Required field when denying referrals
4. Email Notifications: Notify relevant parties when status changes
5. Validation Rules: Prevent invalid status transitions (e.g., can't go from "completed" back to "in_review")
6. Optimistic Updates: Update UI immediately before API call completes
7. Undo Functionality: Allow reverting status changes
8. Batch Updates: Update multiple referrals at once