# Payroll Management System Guide

## Overview
Complete payroll system with EPF/ETF deductions, advance salary management, day-pay calculation, and attendance integration.

## Features

### 1. Salary Structure Management
- **Basic Salary** - Monthly base pay
- **Allowances** - Transport, meal, and other allowances
- **Daily Wage Mode** - Pay per day worked (for casual workers)
- **Day Pay Rate** - Configurable daily rate with history tracking

### 2. EPF/ETF Calculations
Default rates (configurable in Settings):
- **Employee EPF**: 8% of basic salary (deducted)
- **Employer EPF**: 12% of basic salary (company contribution)
- **Employer ETF**: 3% of basic salary (company contribution)

### 3. Advance Salary Management
- Request advances with reason
- Approval workflow (Pending → Approved/Rejected)
- Repayment options:
  - **Lump Sum**: Deduct fully in next payroll
  - **Installments**: Spread over multiple months

### 4. Attendance Integration
Payroll automatically calculates based on attendance:
- Present days = Full pay
- Half days = 0.5 day pay
- Absent days = No pay
- Overtime hours (separate calculation)

### 5. Monthly Payroll Processing
1. Select month/year
2. Click "Calculate" to preview
3. Review individual payslips
4. Click "Process & Save" to finalize
5. Mark as "Paid" when disbursed

## Setup Instructions

### Step 1: Database Migration
Run the SQL file to create payroll tables:
```sql
-- In phpMyAdmin, run:
USE new_sw;
SOURCE database/payroll_schema.sql;
```

Or run the migration script:
```
http://localhost/new_sw/api/payroll.php?action=ensure_schema
```

### Step 2: Configure Settings
Go to **Payroll → Settings** and verify:
- EPF Employee Rate: 8%
- EPF Employer Rate: 12%
- ETF Employer Rate: 3%
- Standard Working Days: 22

### Step 3: Set Up Employee Salary Structures
1. Go to **Payroll → Salary Structure**
2. Select employee from list
3. Enter:
   - Basic salary
   - Allowances (if applicable)
   - Day pay rate (for daily wage employees)
4. Save

### Step 4: Process Monthly Payroll
1. Go to **Payroll → Process Payroll**
2. Select month and year
3. Click **Calculate**
4. Review the calculation summary
5. Check individual payslips by clicking the eye icon
6. Click **Process & Save** to finalize

## Daily Wage Management

For employees paid by day (not monthly):

1. In Salary Structure, check **"Daily Wage Employee"**
2. Set **Day Pay Rate** (e.g., LKR 2,500/day)
3. System automatically calculates: `Days Worked × Day Rate`

### Day Pay Promotions
To increase day pay rate:
1. Go to Salary Structure
2. Enter new rate and effective date
3. Add reason (e.g., "Annual increment", "Promotion")
4. System keeps history of all rate changes

## Reports Available

### 1. EPF/ETF Summary
Shows monthly totals:
- Total basic salaries
- Total EPF (employee + employer)
- Total ETF

### 2. Bank Transfer List
List of employees with:
- Bank account details
- Net salary amounts
- Ready for bank file generation

### 3. Advance Summary
Outstanding advances with:
- Employee name
- Advance amount
- Remaining to repay
- Installment progress

## Integration with Cash Book

When you mark payroll as "Paid":
1. System can create expense entries in cash book
2. Tracks EPF/ETF liabilities
3. Links payment to bank account transactions

## Troubleshooting

### Payroll calculation shows 0 for all employees
- Check if attendance is recorded for the month
- Verify salary structure exists for employees

### EPF/ETF not calculating
- Check payroll settings (rates should be set)
- Ensure employee has basic salary > 0

### Can't see payroll menu
- Check user role (must be admin, accountant, finance_manager, or hr_manager)

## Excel Import (Future Feature)

To import from your existing Excel sheet:
1. Export employees to CSV
2. Use import tool (coming soon)
3. Or manually enter via Salary Structure

## Sample Calculation

**Employee: H.A.H. Premalal (Sales Executive)**
- Basic: LKR 50,000
- Other Allowance: LKR 40,000
- Days Worked: 22
- Overtime: 4 hours

**Calculation:**
```
Basic Salary:        50,000.00
Other Allowance:     40,000.00
Gross:               90,000.00

EPF Employee (8%):    4,000.00
Advance Deduction:   10,000.00
Total Deductions:    14,000.00

NET SALARY:          76,000.00

Employer Contributions:
EPF (12%):            6,000.00
ETF (3%):             1,500.00
```

## Support
For issues or questions, check:
- Browser console for JavaScript errors
- PHP error logs in XAMPP
- Database table `payroll_records` for data issues
