HRM-System/docs/PLAN-multi-branch-attendance.md

PLAN: Multi-Branch Attendance

Target Files:

• branch-agent/sync.js
• app/Http/Controllers/Api/AttendanceSyncController.php
• app/Http/Controllers/BiometricAttendanceController.php
• app/Http/Controllers/AttendanceRecordController.php
• database/migrations/xxxx_add_branch_id_to_attendance_records.php (if needed)

Phase 0: Context & Socratic Alignment

• Problem: Employees travel and clock in at multiple branches. Currently, the dashboard filters attendance based on the Employee's "Home Branch", which hides their records from the branch they actually visited.
• Goal: The dashboard must show attendance records based on where they physically punched in.
• Agent Change: The local agent shouldn't restrict punches. We will keep BRANCH_ID in the .env solely to tell the cloud where the machine is located, but we will remove any restrictions that block employees from other branches.

Phase 1: Database & Sync Engine Updates

1. AttendanceRecord Migration:
   • Check if attendance_records table has a branch_id column. If not, create a migration to add it.
   • This column will store the physical location where the punch happened.
2. Sync Logic (BiometricAttendanceController@syncAll):
   • When converting a biometric_attendance record into a final attendance_record, map the branch_id from the physical ZKTeco punch directly into the attendance_record, bypassing the employee's default home branch.

Phase 2: Web Dashboard & Filtering Updates

1. Dashboard Query (AttendanceRecordController@index):
   • Update the branch filter. Instead of searching employee.branch_id, it must search the attendance_records.branch_id (the actual location of the punch).
   • This ensures Branch Managers can see anyone who clocked in at their building, even if the employee officially belongs to another branch.

Phase 3: Verification Checklist

• Ensure the sync engine correctly assigns the punch location's branch_id to the final attendance record.
• Verify that a Branch Manager can see a visiting employee's punch on their dashboard.
• Verify that the local agent still sends its location identity to the API without blocking unassigned employees.