HRM-System/docs/PLAN-attendance-device-type.md

PLAN: Attendance Device Type (Biometrics vs Web)

1. Context & Objectives

• Objective 1: Track the "source" or "device type" for every clock-in and clock-out event to differentiate between a standard Web Dashboard punch and a physical Biometric device (e.g., ZKTeco) punch.
• Objective 2: Display this device type clearly in the Attendance Record Details UI (view.tsx) so HR and managers know exactly how the employee logged their time.

2. Technical Approach

Phase 1: Database Schema Updates

• Migration: Create a new migration for the attendance_records table to add two new string columns:
  • clock_in_source (nullable, e.g., 'web', 'zkteco', 'manual')
  • clock_out_source (nullable, e.g., 'web', 'zkteco', 'manual')

Phase 2: Backend Logic Integration

• Web Clock-in/out:
  • Update AttendanceRecordController@clockIn to save 'clock_in_source' => 'web'.
  • Update AttendanceRecordController@clockOut to save 'clock_out_source' => 'web'.
• Biometric / ZKTeco Sync:
  • Locate the controller or service responsible for syncing biometrics (e.g., BiometricAttendanceController or a webhook handler).
  • Ensure that when it creates an attendance record from a device punch, it explicitly sets the source to 'zkteco' (or the specific device name if your system supports multiple devices).
• Manual Overrides:
  • If a manager manually creates or edits a record from the admin panel, set the source to 'manual' or 'admin'.

Phase 3: UI Enhancements

• View Modal (view.tsx):
  • Under the Clock In and Clock Out times where we recently added the Location pins, add a new visual indicator (like a small badge or icon) showing the source.
  • Examples: a Laptop icon for "Web", a Fingerprint icon for "Biometric/ZKTeco", and a User-Cog icon for "Manual/HR Override".
• List View / Table (Optional but recommended):
  • Expose the source in the main Attendance Records data grid if useful for filtering.

3. Execution Steps

1. Generate and run database migration to add clock_in_source and clock_out_source.
2. Update AttendanceRecordController to inject the 'web' and 'manual' sources.
3. Update the Biometric sync logic to inject the 'zkteco' source.
4. Update resources/js/pages/hr/attendance-records/view.tsx to display the device/source type with appropriate icons.

4. Open Questions (Socratic Gate)

1. Clock-In vs Clock-Out Sources: Does it happen often that an employee clocks in via the Web but clocks out via ZKTeco (or vice versa)? Should we track the source for both punches individually as proposed, or just a single source for the whole day?
2. Biometric Infrastructure: How are ZKTeco records currently being synced to your system? Do you have an existing cron job, API webhook, or a manual sync button that I will need to update?
3. Specific Device Names: Do you just want it to say "Biometric/ZKTeco", or do you actually want to capture the specific device's IP/Name (e.g., "ZKTeco - Main Gate") if multiple devices exist?