# Payroll deduction breakdown execution checklist

Design and data contract: [Payroll deduction breakdown and UI revision](PAYROLL-DEDUCTION-BREAKDOWN-REVISION.md).

Complete items from top to bottom. Mark an item done only after its work and verification are complete. Steps 1-8 are complete; Step 9 requires an authenticated payroll review.

- [x] **Step 1: Establish the display contract and baseline.** Inspect the component, parent flow, API calculations, loan draft model, and existing helper; record field ownership, reconciliation limits, and UX acceptance criteria in the design document. Verification: read-only source inspection completed; no application file or database changed.
- [x] **Step 2: Confirm payload fields and calculation ownership.** Trace `GET /api/payroll` in live and finalized modes, inspect row normalization and final-net calculations, and confirm cash advance/one-off values do not participate in the active final-net formula. Capture safe fixture examples in focused tests. Verification: source contracts confirm live/finalized field availability; no production payroll was read or changed.
- [x] **Step 3: Implement and test a single deduction mapper.** Keep an applied payroll loan visible when its draft is zero, preserve the API subtotal as authoritative, and cover zero drafts and aggregate reconciliation. Verification: focused mapper tests pass.
- [x] **Step 4: Revise the deduction panel.** Show government contributions, withholding tax, applied loan detail, attendance adjustments, other recorded amounts, and company cost in separate sections. Mark open-ended loans explicitly and show their balance as ongoing. Verification: component test confirms visible groups and scoped payroll total.
- [x] **Step 5: Improve interaction and accessibility.** Add responsive wrapping, semantic section headings, dialog labels, keyboard focus containment, Escape close, focus return, and visible focus states while retaining finalized read-only behavior. Verification: ESLint passes for changed files and the production build succeeds.
- [x] **Step 6: Repair applied-loan detail visibility.** Inspect employee 10844 in the supplied database export, prove that five `loans_json` rows total PHP 3,904.44, then retain applied zero-balance rows in the loan detail component and distinguish them from draft changes. Verification: focused component fixture reproduces the five-row total and passes.
- [x] **Step 7: Implement per-loan live draft editing.** Verify the existing update endpoint payload and guards, add accessible per-loan edit controls and a validated dialog, save through the current draft route, and refresh payroll data from the server. Verification: focused interaction tests, ESLint, and build pass.
- [x] **Step 8: Implement per-loan cutoff revert.** Add a reason-required confirmation, use the audited skip-draft route for previews and the existing unfinalized posted-journal undo route for posted credits, preserve finalized read-only behavior, and refresh the authoritative payroll row. Allow a closed/cancelled loan only for the skip workflow, never for a new deduction. Verification: focused interaction tests, PHP syntax checks, ESLint, and build pass.
- [ ] **Step 9: Complete live and finalized visual reconciliation.** Open one live and one finalized payroll in the authenticated application, inspect desktop and mobile layouts, compare the panel's payroll subtotal to `total_deductions`, and compare attendance adjustments to the net-pay calculation. This needs a real payroll record; no production data was accessed in this implementation session.
- [ ] **Step 10: Complete handoff after Step 9.** Mark the final verification complete and record the live/finalized reconciliation results.

## Verification record

- `npm test -- LoanDetailsMultiApply.test.jsx deductionBreakdown.test.js deductionTemplate.test.jsx` passed after the posted-journal reversal work: 3 test files and 9 tests.
- `npx eslint src/payrollPage/payrollComponents/deductionTemplate.jsx src/payrollPage/payrollComponents/LoanDetailsMultiApply.jsx src/payrollPage/payrollComponents/LoanDetailsMultiApply.test.jsx src/payrollPage/payrollComponents/deductionTemplate.test.jsx` passed.
- `npm run build` passed after the posted-journal reversal work. It emitted two existing unresolved font-path warnings and completed in 1m 8s.
- `php -l backend/payroll/payroll_loan_draft_service.php` and `php -l backend/loan_api/skip_loan_deduction_draft.php` passed. The PHP CLI emitted an existing duplicate `openssl` module warning.
- The component test previously emitted a non-failing jsdom CSS parsing warning from the application stylesheet; the final nine-test run did not emit it.
- `npm test -- LoanDetailsMultiApply.test.jsx` passed: 1 test file and 2 tests, including the default-collapsed loan rows and the open-ended loan status. ESLint also passed for the component and its test.
- `npm test -- deductionTemplate.test.jsx` passed: 1 test file and 5 tests, including the hidden zero-value attendance section. ESLint passed for the deduction template and its test.