HRM-System/docs/PLAN-overtime-approval.md

PLAN: Overtime Approval Workflow

Goal Description

Currently, the HRM system automatically classifies an attendance record as OT (Overtime) on the attendance calendar if the employee exceeds their working hours by more than 1.0 hour.

The objective of this task is to change this behavior so that extra hours only default to a normal P (Present) status. To achieve an OT status, the employee must formally submit an Overtime Request through the dashboard, which an Admin/HR must review and approve. Only approved OT will display as OT on the calendar.

Finalized Requirements

1. Approval Scope: The system will automatically calculate the OT hours based on clock-out time vs shift end time, but the "Apply Overtime" modal will allow the employee (and subsequently HR) to edit the requested/approved hours before final confirmation.
2. Payroll / Reports: The system will prioritize and strictly display "Approved OT Hours". Unapproved OT will be ignored for payroll.
3. Request Triggers: Employees can apply for OT in both ways:
   • A dedicated "Overtime" menu on the dashboard.
   • An "Apply for OT" shortcut button directly inside the daily attendance calendar modal.

---

Proposed Changes

Database Layer

We need a formal table to track these requests.

[NEW] database/migrations/2026_05_05_xxxxxx_create_overtime_applications_table.php

• id, user_id, date, requested_hours, approved_hours, status (pending, approved, rejected, cancelled), reason, admin_remarks, timestamps.

[NEW] app/Models/OvertimeApplication.php

• Eloquent Model defining relationships (belongsTo(User::class)).

Backend Controller Layer

[MODIFY] app/Http/Controllers/AttendanceRecordController.php

• Change the dynamic overlay logic in calendar():
  • Remove the automatic $status = 'OT'; fallback based on $record->overtime_hours >= 1.0.
  • Fetch all Approved OvertimeApplications for the month.
  • If an approved OT application exists for that user/date, overlay the status as OT and label as Overtime (Approved).
  • Otherwise, leave it as P (Present).

[NEW] app/Http/Controllers/OvertimeApplicationController.php

• Full CRUD controller to handle:
  • index() - List user's OT requests (or all requests for Admin).
  • store() - Employee submits an OT request (auto-calculated but editable).
  • approve() / reject() - Admin actions. Administators can override the approved hours before saving.

Frontend UI Layer (React/Inertia)

[MODIFY] resources/js/pages/hr/attendance-records/calendar.tsx

• Ensure the tooltip explicitly states if the OT is approved.
• Add an "Apply for Overtime" button on the daily attendance modal if the user clocked out late. This button will open the Overtime Request form pre-filled with the calculated extra hours.

[NEW] resources/js/pages/hr/overtime/index.tsx

• A dedicated dashboard page (similar to Leave Applications) where employees can view/submit OT requests, and HR can mass-approve them.

---

Verification Plan

Automated / Manual Tests

1. Automatic Fallback Test: Simulate an employee clocking out 3 hours late. Verify the calendar grid shows P, not OT.
2. Approval Flow Test: Submit an Overtime Application for that date.
3. Admin Action Test: Approve the application as Admin.
4. Calendar Overlay Test: Verify the calendar grid now securely shows OT for that date.