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

Goal Description

Achieve 100% data and mathematical parity between the generated Payslip output and the Legacy UI Attendance Chart (Live Data) for all localized employees with complex or flexible work schedules.

User Review Required

Note

Socratic Gate Cleared: Decisions Locked

1. Shift Rule Priority: employee_daily_shifts master schedule overrides raw biometric ping data.
2. Strict Matrix Evaluation: Any missed DB pings on confirmed Working Days will structurally generate Penalty Absences.
3. Native Database Support: is_rest_day will be directly injected into the core AttendanceRecord schema to isolate logic from the Engine.

Proposed Changes

---

Phase 1: Database Schema Expansion

Update the local data infrastructure to natively track flexible rest days on a daily basis.

[MODIFY] database/migrations/..._create_attendance_records_table.php (via new Migration)

Create a new migration add_is_rest_day_to_attendance_records to append boolean('is_rest_day')->default(false).

[MODIFY] app/Models/AttendanceRecord.php

Add is_rest_day to the model's $fillable array.

---

Phase 2: Matrix Sync Algorithm (The "Brain")

Create a powerful artisan CLI tool that scans the legacy employee_daily_shifts and backfills our local system.

[NEW] app/Console/Commands/SyncLegacyDailyShifts.php

1. Iterate over every localized employee across the target Cut-Off period.
2. Query legacy employee_daily_shifts to verify if the iteration day is a Work Day or Rest Day.
3. If it is a Working Day but there is NO raw biometric legacy ping (e.g. Ana on Jan 24), automatically generate an AttendanceRecord row tagged as heavily absent.
4. If it is a Rest Day, generate/update an AttendanceRecord tagged with is_rest_day = true, automatically overriding any false-positive absent tags.

---

Phase 3: Engine Calibration

Revert the temporary Sunday patches from the Payroll Engine and link it straight to the new Schema logic.

[MODIFY] app/Services/PayrollService.php

Remove the hardcoded isSunday() loop rules. Replace it with a pristine mathematical formula:

• If $att->is_rest_day == true -> Mathematically Forgive (Excused).
• If $att->is_absent == true -> Guaranteed Penalty Applied.

Verification Plan

Automated Tests

• Run herd php artisan migrate.
• Run the new matrix herd php artisan import:legacy-shifts.
• Run the core simulation herd php artisan payroll:simulate.
• Automatically output the exact breakdown of the computed penalties dynamically, ensuring 100% synchronization parity with the Physical UI Screenshot (Ana: 4 Absences, Rhea: 6 Absences).