Arshdeep225615024/feature/shift matching system

[Arshdeep225615024]

Shift Matching and Invitation System

Overview

This pull request introduces a new intelligent Shift Matching and Invitation System for the SecureShift backend. The feature allows employers to generate ranked guard recommendations for shifts and invite suitable guards through a structured workflow.

The implementation was designed with minimal disruption to the existing shift lifecycle and assignment system.

---

Features Implemented

Intelligent Shift Matching

Added a new endpoint:

GET /api/v1/shift-matches/:shiftId

The system generates ranked guard recommendations based on:

• Guard availability
• Shift conflict detection
• Verified licence status
• Employer favourite guards
• Same suburb/location matching

---

Suitability Ranking

Replaced simple boolean suitability with ranking levels:

• VERY_HIGH
• HIGH
• MEDIUM
• LOW
• VERY_LOW

Each guard recommendation also includes:

• Numeric score
• Matching reasons/explanations

---

Conflict Detection

Implemented overlapping shift conflict detection.

The system now identifies:

• Time overlaps
• Existing assigned/applied shifts
• Guard scheduling conflicts

Conflicting guards receive reduced scores.

---

Guard Preference System

Added a new GuardPreference model.

Guards can store:

• Preferred shift types
• Preferred fields
• Preferred suburbs
• Minimum pay rate
• Urgent shift preference

Endpoints added:

• GET /api/v1/shift-matches/preferences/me
• POST /api/v1/shift-matches/preferences/me

---

Shift Invitation System

Added a new ShiftInvitation model.

Employers can invite guards directly from match results.

Endpoint added:

• POST /api/v1/shift-matches/:shiftId/invite/:guardId

---

Invitation Management

Guards can:

• View invitations
• Accept or decline invitations

Endpoints added:

• GET /api/v1/shift-matches/invitations/me
• PATCH /api/v1/shift-matches/invitations/:invitationId/respond

---

Role-Based Access Control (RBAC)

Added security restrictions:

• Only employers/admins can generate matches
• Only employers/admins can invite guards
• Only guards can respond to invitations
• Guards can only respond to their own invitations

---

Swagger Documentation

All new functionality has been documented under:

• Shift Matching

Swagger documentation includes:

• Matching endpoints
• Preferences endpoints
• Invitation endpoints
• Invitation response endpoints

---

Workflow

Employer creates shift
→ System generates ranked guard matches
→ Employer invites selected guard
→ Guard views invitation
→ Guard accepts/declines invitation

---

Future Enhancements

Planned future improvements include:

• Automatic shift assignment after invitation acceptance
• Urgent shift mode for last-minute staffing
• Guard-side recommended open shifts

---

Notes

This implementation was intentionally designed to avoid major modifications to the existing shift creation, application, and assignment workflow, ensuring compatibility with the current backend architecture.

[Arshdeep225615024]