# HRM Roles & Permissions

This document describes the role/permission system that protects the HRM application.
Authentication, roles, and permissions are owned by the **eaeuAPI** auth system
(`spatie/laravel-permission`, guard `hrm_api`). The HRM app itself only *enforces*
the permissions the auth system grants.

## How it works

1. A user logs in at `/login`. `LoginController` POSTs to `POST {eaeuAPI}/api/hrm/login`.
2. The auth API returns `{ token, user, roles, permissions }`.
3. `LoginController` stores the token, the roles, and the flat permission-name list
   in the session (`api_token`, `hrm_roles`, `hrm_permissions`).
4. Every protected route runs the `hrm.permission:<name>` middleware
   (`App\Http\Middleware\HrmPermission`), which checks the session's
   `hrm_permissions` array. A route may list several permissions comma-separated;
   holding **any** of them grants access.
5. Requests without the permission get a `403` — JSON for AJAX/API calls, the
   `errors/403` Blade page for browser navigation.

Blade helpers for hiding UI a user cannot use:

```blade
@hrmcan('hrm.employees.create')
    <a href="{{ route('employees.create') }}">إضافة موظف</a>
@endhrmcan

@hrmany(['hrm.payroll.run', 'hrm.payroll.lock'])
    {{-- shown if the user has either permission --}}
@endhrmany
```

The full permission list is also shared with every view as `$hrmPermissions`.

## Seeding

Run in the **eaeuAPI** project:

```bash
php artisan db:seed --class=Database\\Seeders\\RolesAndPermissionsSeeder
```

The seeder is idempotent for the HRM section: it deletes all `hrm_api`-guard roles
and permissions first, then recreates them, so it can be re-run safely.

## Roles

| Role | Arabic | Scope |
|------|--------|-------|
| `hrm-admin` | مدير الموارد البشرية | Everything (all permissions) |
| `hr-manager` | مدير قسم الموارد البشرية | People + payroll + all reports; system-settings read-only |
| `payroll-officer` | مسؤول الرواتب | Full salary engine + reports; employees read-only |
| `hr-specialist` | أخصائي موارد بشرية | Employee records + limited loans/payroll viewing |
| `reports-viewer` | مطّلع على التقارير | Read-only across the app + all reports |

## Permission → Route map

Every permission below is seeded under guard `hrm_api`. GET/index/show routes require
the `.view` permission; write routes require `.create`/`.edit`/`.delete` or `.manage`.

### Employees
| Permission | Routes |
|------------|--------|
| `hrm.employees.view` | `employees.index`, `employees.data`, `employees.show`, `employees.attachments.show`, `api.degrees-by-track`, `api.promotions-by-degree` |
| `hrm.employees.create` | `employees.create`, `employees.store` |
| `hrm.employees.edit` | `employees.edit`, `employees.update` |
| `hrm.employees.delete` | `employees.destroy` |
| `hrm.employees.export` | `employees.export` |

### Employee sub-records
| Permission | Routes |
|------------|--------|
| `hrm.employee-documents.view` | `employees.documents.show` |
| `hrm.employee-documents.create` | `employees.documents.store` |
| `hrm.employee-documents.edit` | `employees.documents.update` |
| `hrm.employee-documents.delete` | `employees.documents.destroy` |
| `hrm.employee-vacations.create` | `employees.vacations.store` |
| `hrm.employee-vacations.edit` | `employees.vacations.update` |
| `hrm.employee-vacations.delete` | `employees.vacations.destroy` |
| `hrm.employee-qualifications.create` | `employees.qualifications.store` |
| `hrm.employee-qualifications.edit` | `employees.qualifications.update` |
| `hrm.employee-qualifications.delete` | `employees.qualifications.destroy` |
| `hrm.employee-trainings.create` | `employees.trainings.store` |
| `hrm.employee-trainings.edit` | `employees.trainings.update` |
| `hrm.employee-trainings.delete` | `employees.trainings.destroy` |
| `hrm.employee-punishments.create` | `employees.punishments.store` |
| `hrm.employee-punishments.edit` | `employees.punishments.update` |
| `hrm.employee-punishments.delete` | `employees.punishments.destroy` |

### Reference data
| Permission | Routes |
|------------|--------|
| `hrm.departments.view` / `.manage` | `reference.departments.*` |
| `hrm.jobs.view` / `.manage` | `reference.jobs.*` |
| `hrm.degrees.view` / `.manage` | `reference.degrees.*` |
| `hrm.job-tracks.view` / `.manage` | `reference.job-tracks.*` |
| `hrm.reference-data.view` / `.manage` | all other `reference.*` lookups: banks, genders, marital-statuses, hire-types, qualifications, religious, service-types, taxation-types, vacation-types, punishment-types, document-types, bonus-types, counters, allowances, deductions, taxation-ranges, transportation-types, loan-types, job_natures |

### Allowances / Deductions / Tax
| Permission | Routes |
|------------|--------|
| `hrm.allowances.view` | `allowances.matrix`, `allowances.employee-overrides`, `allowances.employee.show`, `allowances.suspensions` |
| `hrm.allowances.manage-matrix` | `allowances.matrix.save`, `allowances.matrix.delete` |
| `hrm.allowances.employee-override` | `allowances.employee.store/update/destroy` |
| `hrm.allowances.suspension` | `allowances.suspensions.toggle/destroy` |
| `hrm.deductions.view` | `deductions.matrix`, `deductions.job`, `deductions.employee.show` |
| `hrm.deductions.manage-matrix` | `deductions.matrix.save/delete` |
| `hrm.deductions.job-mapping` | `deductions.job.save/delete` |
| `hrm.deductions.employee-override` | `deductions.employee.store/update/destroy` |
| `hrm.tax.view` | `tax.settings` |
| `hrm.tax.manage` | `tax.toggle`, `tax.taxable.*`, `tax.ranges.*`, `tax.housing.save` |

### Loans
| Permission | Routes |
|------------|--------|
| `hrm.loans.view` | `loans.index`, `loans.report`, `loans.employee.index`, `loans.employee.show` |
| `hrm.loans.create` | `loans.employee.store` |
| `hrm.loans.edit` | `loans.employee.update` |
| `hrm.loans.delete` | `loans.employee.destroy` |
| `hrm.loans.finalize` | `loans.finalize`, `loans.reopen` |
| `hrm.loans.pay-installment` | `loans.installments` |
| `hrm.general-loans.view` | `general-loans.index` |
| `hrm.general-loans.manage` | `general-loans.create/edit/destroy` |

### Payroll & Promotions
| Permission | Routes |
|------------|--------|
| `hrm.payroll-cycles.view` | `payroll-cycles.index` |
| `hrm.payroll-cycles.manage` | `payroll-cycles.create/store/edit/update/destroy` |
| `hrm.promotions.view` | `promotions.index` |
| `hrm.promotions.manage` | `promotions.add-level`, `promotions.save-matrix` |
| `hrm.payroll.view` | `payroll.index`, `payroll.validate`, `payroll.status`, `payroll.history` |
| `hrm.payroll.run` | `payroll.run`, `payroll.run-diff`, `payroll.run-extra` |
| `hrm.payroll.lock` | `payroll.lock`, `payroll.unlock` |
| `hrm.payroll.correction` | `payroll.correction` |
| `hrm.payroll.sheets` | `payroll.paysheet`, `payroll.statements`, `payroll.diff-sheet`, `payroll.extra-sheet` |

### Reports
| Permission | Routes |
|------------|--------|
| `hrm.reports.dashboard` | `reports.index`, `reports.dashboard`, `reports.dashboard-data` |
| `hrm.reports.salary-slip` | `reports.salary-slip`, `reports.salary-slips-bulk` |
| `hrm.reports.payroll-sheet` | `reports.payroll-sheet-pdf`, `reports.payroll-sheet-excel` |
| `hrm.reports.bank-transfer` | `reports.bank-transfer` |
| `hrm.reports.department-summary` | `reports.department-summary` |
| `hrm.reports.salary-budget` | `reports.salary-budget` |
| `hrm.reports.salary-reconciliation` | `reports.salary-reconciliation` |
| `hrm.reports.vacations` | `reports.vacations.employee`, `reports.vacations.general` |

### System settings
| Permission | Routes |
|------------|--------|
| `hrm.system-settings.view` | `system-settings.index` |
| `hrm.system-settings.manage` | `system-settings.update`, `system-settings.reset` |

## Unprotected authenticated routes

`logout` and `dashboard` require only a valid token (no specific permission).