HRM-System/docs/PLAN-payroll-parallel-fixes.md

PLAN: Payroll Parallel Fixes

Overview

This plan addresses the UI navigation and core payroll computation errors discovered during the parallel testing phase (from Payroll-Parallel-1.pdf). It covers resolving the inline PDF download issue, synchronizing LWOP/Leaves/Undertime with the payroll engine, correcting phantom holiday pay, and properly branching computations for Rank & File (Daily Wage) vs. Fixed Salary employees.

Project Type

WEB (Backend & Frontend)

Success Criteria

• Users can download payslips properly and navigate back without refreshing the page.
• Tardiness, LWOP, Undertime, and Approved Leaves reflect accurately in the payslip's deduction and summary sections.
• Holiday Pay only applies when actual holidays are set and valid.
• Rank & File (Daily Wage) employees have their salary computed correctly (Daily Rate x Days Worked) instead of (Monthly / 2).

Tech Stack

• Frontend: React, TypeScript, Inertia.js (for UI/Navigation fixes)
• Backend: Laravel, PHP, MySQL (for PayrollService.php computations)

File Structure (Anticipated Changes)

• app/Http/Controllers/PayslipController.php (or equivalent backend file returning PDF)
• resources/js/pages/... (Frontend view component handling the Payslip UI)
• app/Services/PayrollService.php

Task Breakdown

Phase 1: UI / Navigation Fix

• task_id: 1.1
• name: Fix Payslip Download Header & Navigation
• agent: @frontend-specialist
• skills: react-best-practices
• priority: HIGH
• dependencies: None
• INPUT: PayslipController PDF response and frontend payslip view component.
• OUTPUT: Change inline to attachment header (or add a distinct download endpoint). Implement window.history.back() or Inertia Link for the back button.
• VERIFY: Clicking download saves the PDF to the user's local disk; users can click "Back" to return to the list without a hard refresh.

Phase 2: Native Attendance Recalculation (No Legacy DB)

• task_id: 2.1
• name: Recalculate Late/Undertime Natively
• agent: @backend-specialist
• skills: clean-code
• priority: CRITICAL
• dependencies: None
• INPUT: AttendanceRecord and Shift models
• OUTPUT: Write a one-time script/command that loops through all current local attendance_records. It will compare the actual clock_in time against the assigned Shift's start_time, and natively compute and save the exact late_hours and is_late values directly. No legacy database needed.
• VERIFY: Generate a test payslip for Paul Rei Paas and verify the late penalty precisely matches his tardiness minutes based on his local clock-in data.

Phase 3: Leave and Holiday Reconciliation

• task_id: 3.1
• name: Correct Leave Display and Phantom Holiday Pay
• agent: @backend-specialist
• skills: clean-code
• priority: HIGH
• dependencies: Task 2.1
• INPUT: PayrollService.php
• OUTPUT: Fix the holiday calculation query to only include system-defined holidays for the specific cut-off date range. Ensure Sick, Vacation, and Birthday leaves are pulled into the attendance summary payload.
• VERIFY: Generate a payslip for Ana Regina Mariano and confirm zero Holiday Pay is added, and her Birthday Leave is reflected in the summary.

Phase 4: Daily Wage Computation Branching

• task_id: 4.1
• name: Branch Logic for Rank & File Earners
• agent: @backend-specialist
• skills: clean-code
• priority: CRITICAL
• dependencies: None
• INPUT: PayrollService.php
• OUTPUT: Implement an if ($employee->type === 'daily_wage') branch. Calculate gross pay as (Daily Rate x Days Worked) instead of the default fixed cut-off logic.
• VERIFY: Run a test generation for Dinh Chavez (Rank & File) and verify the gross pay explicitly equals their specific Daily Rate multiplied by their exact days worked.

Phase X: Verification

• Run python .agent/scripts/lint_runner.py .
• Run python .agent/scripts/test_runner.py .
• Manual test: Verify Payslip UI.
• Manual test: Verify PDF data calculations match expected outputs.