Feature Specification: Payroll Management

1. Overview & Vision

The Payroll module manages the end-to-end pay run process — from salary and bank account mapping through tax resolution to final pay run processing. It provides HR with a ledger-based view of all compensation changes and ensures compliance with local tax regulations.

2. Personas & Stakeholders

Persona	Goal
Employee	View their salary breakdown and payslips.
HR Admin	Run monthly payroll, review tax calculations, and maintain salary records.
Finance	Audit the payroll ledger and export for accounting.

3. User Stories

• As HR, I want to run payroll for April and see a breakdown by department before confirming.
• As an employee, I want to see my net salary and deductions for last month.
• As Finance, I want to export the payroll ledger as CSV for our accounting system.

4. Functional Requirements (FR)

• REQ-PAY-001: Salary record per employee with effective date (enables time-travel lookup).
• REQ-PAY-002: Bank account mapping — employee links their bank details; encrypted at rest.
• REQ-PAY-003: Tax resolution engine — applies tax brackets and social insurance rules to gross salary.
• REQ-PAY-004: Pay run processing — HR triggers a pay run for a period; system calculates net pay for all employees.
• REQ-PAY-005: Pay run summary — aggregate view by department with total gross, deductions, and net.
• REQ-PAY-006: Payslip per employee — downloadable PDF with salary breakdown.
• REQ-PAY-007: Four-Eyes approval — salary changes require a second HR approver.

5. Non-Functional Requirements (NFR)

• Accuracy: Tax calculations must be deterministic and reproducible (same inputs = same output).
• Immutability: Confirmed pay runs are locked — no edits after confirmation.
• Security: Salary and bank data classified as sensitive; encrypted at rest with AES-256-GCM.

6. Business Logic & Rules

• Effective Date: Salary changes take effect from the specified date; pay run uses the salary active during the pay period.
• Tax Resolution: Applies configurable tax brackets; social insurance deducted before income tax.
• Four-Eyes: A salary update submitted by HR User A must be approved by a different HR User B before taking effect.
• Pay Run Lock: Once a pay run is confirmed, all records become immutable. Corrections require a new adjustment pay run.

7. User Interface (UI/UX)

• Salary tab on Employee Profile: salary history timeline, current effective salary.
• Payroll page: pay run list, trigger new run button, department breakdown table.
• Pay Run detail: employee rows with gross / deductions / net; confirm/cancel actions.

8. Information Architecture

• "Payroll" section in HRM sidebar (HR Admin only).
• "My Payslips" tab on Employee Profile (self-service).

9. Data Model & Persistence

• Tables: salary_records (effective date, gross, currency), bank_accounts (encrypted), pay_runs, payroll_line_items.
• Audit: Every salary change appended to the ledger — old value, new value, changed by, approved by.

10. API & Service Layer

• GET /payroll/pay-runs
• POST /payroll/pay-runs — trigger new pay run
• POST /payroll/pay-runs/:id/confirm
• GET /employees/:id/salary-history
• POST /employees/:id/salary — propose salary change (requires approval)

11. Integration Patterns

• Attendance: Pay run includes overtime hours from the Attendance module.
• Leave: Unpaid leave days are deducted from gross before tax calculation.
• Shell: Salary data is never synced to Shell — stays within HRM's security boundary.

12. Security & Permissions

• RBAC: payroll:read for HR; payroll:run for Payroll Admin; payroll:approve_salary required for Four-Eyes.
• Masking: Salary amounts masked for non-HR roles (***); bank account numbers partially masked.

13. Error Handling & Resilience

• Pay run with missing salary record fails with a clear list of affected employees.
• Duplicate pay run for the same period returns 409 Conflict.

14. Performance & Scalability

• Pay run calculation is processed as a background job for large organizations (>500 employees).
• Payslip PDFs generated on-demand and cached for 24 hours.

15. Globalization & i18n

• Currency and tax rules configurable per organization locale.
• Payslips generated in the employee's preferred language.

16. Accessibility (a11y)

• Payroll tables have proper column headers and ARIA roles.

17. Observability & Analytics

• Pay run duration tracked for performance monitoring.
• Total payroll cost per department feeds into the Analytics module.

18. Testing & Quality

• Unit tests for tax resolution and pay run processing logic.
• Integration tests for the Four-Eyes approval flow.
• Immutability tests for confirmed pay runs.

19. Constraints & Assumptions

• Single currency per organization (multi-currency planned for v2).
• Tax rules must be configured by HR Admin before first pay run.

20. Future Enhancements

• Multi-currency support.
• Direct bank transfer integration.
• Automated tax filing export (VAS, e-invoice).