# Task 22 — Payroll

## Goal
Build the Payroll module to manage salary runs for employees and prepare payroll data for summary reporting and future finance integration.

---

## Database

### Table: `payrolls`

Fields:
- id
- payroll_number (string, unique)
- employee_id (FK to employees.id)
- branch_id (nullable, FK to branches.id)
- payroll_month (date)
- basic_salary (decimal 18,2)
- allowances (decimal 18,2 default 0)
- deductions (decimal 18,2 default 0)
- net_salary (decimal 18,2 default 0)
- status (string, default `draft`)
  - draft
  - approved
  - paid
- notes (json, nullable, translatable)
- created_by (nullable, FK to admins.id)
- updated_by (nullable, FK to admins.id)
- created_at
- updated_at

Indexes:
- unique payroll_number
- index employee_id
- index branch_id
- index payroll_month
- index status

---

## Relations

Payroll model relations:
- employee() -> belongsTo Employee
- branch() -> belongsTo Branch
- creator() -> belongsTo Admin
- updater() -> belongsTo Admin

---

## Business Rules

1. Payroll number must be unique and can use NumberSequenceService.
2. Payroll belongs to one employee and one payroll month.
3. net_salary = basic_salary + allowances - deductions.
4. Payroll starts as `draft`.
5. Later tasks may add finance posting and payment workflow.
6. Notes must use HasTranslations.

---

## Files

### Model
- app/Models/HR/Payroll.php

### Service
- app/Services/HR/PayrollService.php

### Controller
- app/Http/Controllers/Admin/HR/PayrollController.php

### Requests
- app/Http/Requests/Admin/HR/StorePayrollRequest.php
- app/Http/Requests/Admin/HR/UpdatePayrollRequest.php

### Views
- resources/views/dashboard/hr/payroll/index.blade.php
- resources/views/dashboard/hr/payroll/create.blade.php
- resources/views/dashboard/hr/payroll/edit.blade.php
- resources/views/dashboard/hr/payroll/show.blade.php

### Lang files
- lang/ar/hr.php
- lang/en/hr.php

---

## Permissions

- hr.payroll.view
- hr.payroll.create
- hr.payroll.update
- hr.payroll.run

---

## Validation Rules

- employee_id: required, exists:employees,id
- branch_id: nullable, exists:branches,id
- payroll_month: required, date
- basic_salary: required, numeric, min:0
- allowances: nullable, numeric, min:0
- deductions: nullable, numeric, min:0
- status: nullable, in:draft,approved,paid
- notes.ar: nullable, string
- notes.en: nullable, string

---

## UI

Views path:
`resources/views/dashboard/hr/payroll/`

Fields in form:
- employee
- branch
- payroll_month
- basic_salary
- allowances
- deductions
- net_salary
- status
- notes_ar
- notes_en

Index columns:
- payroll_number
- employee
- payroll_month
- net_salary
- status
- actions

---

## Lang Keys

Suggested keys:
- payroll
- payrolls
- create_payroll
- edit_payroll
- payroll_number
- payroll_month
- basic_salary
- allowances
- deductions
- net_salary
- status
- draft
- approved
- paid
- employee
- branch

---

## Seeder

Update RolePermissionSeeder with:
- hr.payroll.view
- hr.payroll.create
- hr.payroll.update
- hr.payroll.run

---

## Steps

### Step 1
Create migration for `payrolls` table.

### Step 2
Create `Payroll` model with HasTranslations for notes.

### Step 3
Create `PayrollService`.

### Step 4
Create Form Requests.

### Step 5
Create `PayrollController`.

### Step 6
Create routes.

### Step 7
Create views.

### Step 8
Create lang files.

### Step 9
Update `RolePermissionSeeder`.

---

## Notes for AI

- Follow docs/ai/AI_MASTER_PROJECT.md
- Follow docs/ai/ARCHITECTURE_RULES.md
- Follow docs/ai/DATABASE_SCHEMA.md
- Follow docs/ai/MODULE_STRUCTURE.md
- Execute one step at a time
- Do not modify unrelated files
- Do not generate tests in this task
- Wait for confirmation after each step