HRM-System/docs/PLAN-biometric-sync.md

Biometric Attendance Synchronization Assessment & Manual Pairing Plan

This plan documents the current integration state between the biometric devices, the Windows Sync Agent, and the core HRMS attendance records, and proposes a design for enhanced manual pairing when multiple daily pings occur.

---

🔍 Codebase Assessment Findings

1. The Sync Pipeline Architecture

The system uses a pull-then-push architecture split into three main parts:

1. Branch Sync Agent (branch-agent/sync.js):
   • A packaged Node.js script (sync-agent.exe) running locally on a branch PC.
   • It queries the local ZKTeco biometric device via TCP (port 4370) using the zklib-js library.
   • It filters pings to the last 15 days and sends an HTTP POST request with an API key to the cloud API endpoint: /api/zkteco/sync.
2. Receiving API (AttendanceSyncController@sync):
   • Authenticates the agent using the ZKTECO_SYNC_KEY (configured in .env).
   • Receives the JSON payload and registers punches in the biometric_attendances table with a state of pending. It avoids duplicates by checking biometric_emp_id and punch_time.
3. Attendance Mapping & Conversion (BiometricAttendanceController):
   • Is it synced automatically? No. It is currently designed to be manually triggered by an HR administrator from the /hr/biometric-attendance dashboard.
   • How it works:
     • Bulk Trigger (Pull Data & Sync button): Loops through all pending biometric records, groups them by employee + date, takes the first entry as clock_in, the last entry as clock_out (requires at least 2 pings), creates an AttendanceRecord, and processes payroll hours.
     • Row Trigger (Sync action): Syncs a single employee-day grouping using the first/last punch logic.

---

🛠️ Proposed Improvements: Manual Triggering & Multiple Punch Pairing

Currently, if an employee has multiple entries (e.g., Clock In, break pings, Clock Out), the system automatically picks the first and last. If the user wants to manually pair custom punch times (e.g. ignoring a false scan or choosing a specific middle scan):

Phase 1: Database Schema Support

No schema changes are required as BiometricAttendance records already store the individual raw punch timestamps and can be marked as synced individually.

Phase 2: Backend Controller Updates (BiometricAttendanceController)

• [New Endpoint] Custom Sync Pairing (/hr/biometric-attendance/sync-custom):
  • Accept a custom POST request containing employee_code, date, clock_in_biometric_id, and clock_out_biometric_id.
  • Fetch the specific biometric records by ID to extract the custom clock-in and clock-out times.
  • Insert/update the AttendanceRecord with these custom values.
  • Mark all biometric entries for that employee/date as synced.

Phase 3: Frontend UI Enhancements (resources/js/pages/hr/biometric-attendance/index.tsx)

• Enhance the Details Modal (View component) to display checkbox selectors or action buttons next to the list of pings for a specific day.
• Allow HR to check one ping as the desired "Clock In" and another ping as the "Clock Out".
• Provide a "Confirm Custom Sync" button in the modal that triggers the new custom pairing endpoint.

---

📋 Verification Plan

Automated Verification

• Run npm run build to verify React components bundle correctly with Shadcn UI additions.
• Execute unit/integration tests for the new sync-custom endpoint.

Manual Walkthrough

1. Agent Simulation: Push mock data containing 4 punches for an employee on a single day to /api/zkteco/sync.
2. Dashboard Review: View the record on the /hr/biometric-attendance page (it will show 4 total entries).
3. Details Pairing: Click "Details" (Eye icon), select Punch #1 as Clock In and Punch #4 as Clock Out, and click "Confirm Custom Sync".
4. Attendance Parity: Verify that the generated AttendanceRecord matches the chosen times, and all 4 logs are marked as synced.