HRM-System/docs/PLAN-refactor-payroll-run.md

Integrate DOLE PayrollService into PayrollRun Pipeline

Analysis & Context

The user observed that when creating a new Payroll Run (e.g., Run ID 31), the data generated inside the PayrollEntry rows severely misaligns with the correct Cut-Off/Payslip basis. While we already built the robust 2025 DOLE-compliant PayrollService.php math engine earlier, the PayrollRun model was bypassing it entirely because it contained a heavily outdated, 200-line hard-coded duplicate calculation script inside its processEmployeePayroll() method.

This legacy block forces a full monthly gross mapping directly into the row, dividing incorrectly across working days rather than automatically snapping to the cut-off basis (Semi-Monthly, Bi-weekly, etc) natively calculated by the PayrollService, yielding a fractured front-end display.

Proposed Changes

We must strictly abandon the legacy hard-coded math block inside the PayrollRun model and route all run computations into the single unified PayrollService math layer.

[MODIFY] app/Models/PayrollRun.php

• Completely delete the 150+ lines of duplicate computation code residing inside processEmployeePayroll().
• Inject a call directly to (new \App\Services\PayrollService())->calculateForPeriod($employee, $this->pay_period_start, $this->pay_period_end)
• Map the high-fidelity $result output (which properly accounts for the accurate standard cut-off basis, absences, SSS matrices, and daily rates) logically back into the PayrollEntry::create pipeline map:
  • basic_salary -> maps to $result['basic_salary']
  • per_day_salary -> maps to $result['daily_rate']
  • absent_days -> maps to $result['summary']['absences']
  • net_pay -> maps to $result['net_pay']
  • earnings_breakdown -> maps to the $result['earnings'] JSON array.
  • deductions_breakdown -> maps to the $result['deductions'] JSON array.

Verification Plan

1. Completely refresh the database slate using artisan tinker to remove the corrupted entries.
2. Build a fresh test run on /hr/payroll-runs.
3. Process it and independently verify that the Basic Salary Basis column perfectly matches $13,000 (for a 26k earner on Semi-Monthly) and absent math matches the DOLE evaluation grid exactly!