83 lines
4.6 KiB
Markdown
83 lines
4.6 KiB
Markdown
# HRM Payroll Processing Workflow
|
|
> Comprehensive architectural and operational guide to the payroll lifecycle.
|
|
|
|
## Core Lifecycle Flow
|
|
1. **Employee Onboarding** -> 2. **Shift Management** -> 3. **Attendance Tracking** -> 4. **Payroll Run (Cut-off)** -> 5. **Manual/Statutory Edits** -> 6. **Final Generation**
|
|
|
|
```mermaid
|
|
graph TD
|
|
A[Create Employee] -->|Validate Required Fields| B(Create Shift)
|
|
B --> C(Assign Shift in Calendar)
|
|
C --> D{Attendance Tracking}
|
|
D -->|Manual Entry| E[Attendance Records]
|
|
D -->|CSV/Excel Import| E
|
|
D -->|Employee Clock In/Out| E
|
|
E --> F[Create Payroll Run Cut-off]
|
|
F --> G[Process Payroll Engine]
|
|
G --> H{Requires Adjustments?}
|
|
H -->|Yes| I[Edit Payroll Entry / Statutory Edits]
|
|
I --> J
|
|
H -->|No| J[Generate / Complete Payroll]
|
|
```
|
|
|
|
---
|
|
|
|
## 1. Employee Creation & Validation
|
|
**Controller:** `EmployeeController@store`
|
|
|
|
The process begins by onboarding an employee and ensuring all critical data is present.
|
|
- **Required Fields:** Name, Email, Password, Phone, DOB, Gender, Salary, Branch, Department, Designation, Date of Joining, Employment Type, Status, Full Address, Emergency Contact, and Bank Details.
|
|
- **Document Validation:** The system strictly enforces the upload of mandatory documents defined in `DocumentType` (e.g., ID, Contract).
|
|
- **Outcome:** Creates a `User` model linked to an `Employee` model.
|
|
|
|
## 2. Shift Creation
|
|
**Controller:** `ShiftController@store`
|
|
|
|
Before assigning attendance, valid shifts must be created.
|
|
- **Parameters:** Name, Start Time, End Time, Break Duration, Grace Period, and Night Shift toggle.
|
|
- **Validation:** Ensures no duplicate shift names exist per company.
|
|
|
|
## 3. Shift Assignment (Calendar)
|
|
**Controller:** `ShiftController@assignShift`
|
|
|
|
Shifts are assigned to employees over a specific date range (or marked as Rest Days).
|
|
- **Process:** The system iterates through the date range (`CarbonPeriod`) and uses `AttendanceRecord::updateOrCreate` to generate blank attendance records for the scheduled shifts.
|
|
- **Default Status:** Scheduled days are given a default status of `present` or `absent` (if it's a rest day) pending actual clock-ins.
|
|
|
|
## 4. Attendance Entry & Import
|
|
**Controller:** `AttendanceRecordController`
|
|
|
|
Attendance data populates the assigned shifts to reflect actual hours worked.
|
|
- **Manual Entry (`@store`):** HR administrators can manually input records, specifying `clock_in`, `clock_out`, and `status` (present, absent, half_day, on_leave, holiday).
|
|
- **Import (`@fileImport`):** Bulk attendance data can be imported via CSV/Excel. The system matches records by employee name and date, respecting the employee's assigned shift and attendance policy.
|
|
- **Clock In/Out:** Employees can log their own time, which updates the `AttendanceRecord` dynamically.
|
|
- **Processing:** `processAttendance()` is called to calculate total hours, late arrivals, and overtime.
|
|
|
|
## 5. Payroll Run & Processing (Cut-off)
|
|
**Controller:** `PayrollRunController@store` & `@process`
|
|
**Model:** `PayrollRun::processPayroll()`
|
|
|
|
When the pay period concludes, a Payroll Run is generated.
|
|
- **Initialization:** Created in a `draft` status for a specific pay period (Start Date to End Date).
|
|
- **Processing Engine:** When "Process" is clicked, the system queries all active employees and passes them to the `App\Services\PayrollService` engine.
|
|
- **Calculation:** The engine evaluates the attendance records within the cut-off period against the employee's base salary to calculate:
|
|
- Working days, Present days, Absences, and Leaves
|
|
- Basic Salary and Component Earnings
|
|
- Overtime Amount and Deductions (DOLE compliant)
|
|
- **Outcome:** Creates a `PayrollEntry` for each processed employee.
|
|
|
|
## 6. Statutory Edits & Adjustments
|
|
**Controller:** `PayrollRunController@updateEntry`
|
|
|
|
Before finalizing, HR/Payroll officers can review and adjust individual employee payroll entries.
|
|
- **Adjustments:** Users can modify `basic_salary`, `component_earnings`, `overtime_amount`, `unpaid_leave_deduction`, and `total_deductions`.
|
|
- **Recalculation:** The system automatically recalculates `total_earnings`, `gross_pay`, and `net_pay` (`Gross Pay = Total Earnings`, `Net Pay = Gross Pay - Total Deductions`).
|
|
- **Top-Level Update:** Updating an entry triggers `PayrollRun->calculateTotals()` to ensure the parent run reflects the new amounts.
|
|
|
|
## 7. Generation & Completion
|
|
**Controller:** `PayrollRunController` (Status Update)
|
|
|
|
Once all entries are verified and statutory edits are completed, the payroll run is finalized.
|
|
- **Action:** The status is updated from `draft` to `completed`.
|
|
- **Finality:** Once completed, the payroll entries are locked, and Payslips are ready for distribution and export.
|