HRM-System/docs/PLAN-clock-in-radius-warning.md

PLAN - Out of Radius Clock-In Warning

1. Context & Objective

The user wants to remove the explicit "Location Exempt" toggle from the employee profile. Instead, the new behavior should apply to all employees: they can clock in/out from anywhere, but if they attempt to clock in/out outside of the designated branch radius (or without location data), they should be presented with a confirmation modal warning them that they are out of bounds.

The objective is to:

1. Remove is_location_exempt fields from the Employee forms.
2. Modify AttendanceRecordController to remove the strict geofence block and instead return a warning trigger to the frontend.
3. Update employee-dashboard.tsx to catch this warning, display a confirmation modal, and allow the user to force the clock-in/out.

2. Target Files

• resources/js/pages/hr/employees/create.tsx
• resources/js/pages/hr/employees/edit.tsx
• app/Http/Controllers/EmployeeController.php
• app/Http/Controllers/AttendanceRecordController.php
• resources/js/pages/employee-dashboard.tsx

3. Task Breakdown

Phase 1: Clean up Employee Forms and Controller

• Remove the is_location_exempt Switch, Label, and Tooltip from create.tsx and edit.tsx.
• (Optional but recommended) Remove is_location_exempt handling in EmployeeController.php to clean up the backend.

Phase 2: Modify Attendance Logic (Backend)

• In AttendanceRecordController.php (clockIn and clockOut), remove the if (!$user->is_location_exempt) condition.
• Add a check for $request->input('force_location', false).
• If the employee is out of radius or location is missing, and force_location is false, return redirect()->back()->with('location_warning', __('You are outside the required branch radius. Do you want to proceed?')); instead of an error.
• If force_location is true, bypass the radius check and allow the clock in/out.

Phase 3: Implement Confirmation Modal (Frontend)

• In employee-dashboard.tsx, add state variables: showLocationWarningModal (boolean), pendingAction ('in' | 'out' | null), and pendingCoords (latitude/longitude).
• Update sendClockInRequest and sendClockOutRequest to accept a force boolean parameter (defaults to false).
• Pass force_location: force in the request payload.
• In the Inertia onSuccess callback, check if page.props.flash?.location_warning exists. If so, open the modal and save the action and coords to state.
• Create a <Dialog> component (Confirmation Modal) that asks the user if they want to proceed.
• On Confirm, call sendClockInRequest or sendClockOutRequest with the saved coords and force = true.

4. Verification Checklist

• Verify is_location_exempt is removed from Add/Edit Employee pages.
• Clock in while outside the radius and verify the modal appears.
• Confirm the modal and verify the clock in is successful.
• Repeat the test for clocking out.