feat: Auto-detect exhausted priorities and transition mentee to PENDING_MANUAL_MATCH

[womencodingcommunity]

Context

When a mentee has exhausted all their priority applications (all declined, unavailable, expired, or rejected), instead of immediately marking NO_MATCH_FOUND, the system should place them in a PENDING_MANUAL_MATCH queue so admins have a chance to manually find a mentor before giving up.

Changes Required

Internal service method — checkAndTriggerManualMatch(menteeId, cycleId)

• Called internally after every forwarding action (MENTOR_DECLINED, MENTOR_UNAVAILABLE, ADMIN_FORWARDED, REJECTED)
• Checks if all applications for this mentee+cycle are in a terminal or non-forwardable state
• If yes: creates a placeholder MenteeApplication record with no mentorId, status PENDING_MANUAL_MATCH, to represent the manual matching queue entry

New admin query endpoint

GET /api/platform/v1/mentees/pending-manual-match?cycleId={cycleId}
Response: List of mentees awaiting manual matching, ordered by date exhausted

Placeholder application design

• A new application record is created with mentorId = null and status PENDING_MANUAL_MATCH
• This record serves as the queue entry and anchor for subsequent admin actions (assign or confirm no match)

Acceptance Criteria

• checkAndTriggerManualMatch() called after every forwarding action
• Placeholder application created when all priorities exhausted
• GET /pending-manual-match endpoint returns correct mentees
• Unit tests for exhaustion detection logic
• Integration test: register 5 applications, decline all, verify PENDING_MANUAL_MATCH

Dependencies

• Ticket: feat: Add new ApplicationStatus values and DB migration
• Ticket: feat: Admin API to reject mentor-mentee pairing
• Ticket: feat: Admin API to mark mentor unavailable and forward