# Task 23 — Payroll Summary

## Goal
Build the Payroll Summary report module to provide payroll totals by employee, branch, and payroll month.
This report summarizes HR payroll activity for management and future finance reconciliation.

---

## Scope

This task covers:
- payroll summary query logic
- filters by branch / employee / payroll month
- report UI
- totals for payroll figures

This task does NOT cover:
- payroll posting to finance
- advanced salary analytics
- export implementation

---

## Data Source

Primary source table:
- `payrolls`

Supporting tables:
- `employees`
- `branches`

---

## Required Output

For each row:
- payroll_number
- employee_name
- branch_name
- payroll_month
- basic_salary
- allowances
- deductions
- net_salary
- status

Summary section:
- total employees
- total basic salary
- total allowances
- total deductions
- total net salary

---

## Business Rules

1. Payroll Summary must read from `payrolls`.
2. Filters must support:
   - branch_id (optional)
   - employee_id (optional)
   - payroll_month (optional)
3. Employee name must use translated JSON field.
4. If no payroll records exist for the selected filter, return empty result safely.
5. Later tasks may add export and finance reconciliation.

---

## Query Rules

Main joins:
- payrolls
- employees
- branches

Suggested filters:
- branch_id
- employee_id
- payroll_month

Order by:
- payroll_month desc
- payrolls.id desc

---

## Files

### Service
- app/Services/HR/Reports/PayrollSummaryService.php

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

### Requests
- app/Http/Requests/Admin/HR/PayrollSummaryFilterRequest.php

### Views
- resources/views/dashboard/hr/reports/payroll_summary/index.blade.php

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

---

## Permissions

- hr.payroll_summary.view

---

## Validation Rules

- branch_id: nullable, exists:branches,id
- employee_id: nullable, exists:employees,id
- payroll_month: nullable, date

---

## UI

Views path:
`resources/views/dashboard/hr/reports/payroll_summary/`

### Filter fields
- branch
- employee
- payroll_month
- submit button

### Table columns
- payroll_number
- employee
- branch
- payroll_month
- basic_salary
- allowances
- deductions
- net_salary
- status

### Summary cards/section
- total_employees
- total_basic_salary
- total_allowances
- total_deductions
- total_net_salary

---

## Lang Keys

Suggested keys:
- payroll_summary
- payroll_number
- employee
- branch
- payroll_month
- basic_salary
- allowances
- deductions
- net_salary
- status
- total_employees
- total_basic_salary
- total_allowances
- total_deductions
- total_net_salary
- filter
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- hr.payroll_summary.view

---

## Steps

### Step 1
Create `PayrollSummaryFilterRequest`.

### Step 2
Create `PayrollSummaryService`.

### Step 3
Create `PayrollSummaryController`.

### Step 4
Add routes in `routes/admin.php`.

### Step 5
Create payroll summary view.

### Step 6
Create lang files.

### Step 7
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