# FCE(T) Gombe — HR & Payroll System
## User Guide

> Audience: HR, Bursary, Auditors, Administrators and self-service staff.
> A step-by-step guide to every part of the system. For technical/architecture details see **TECHNICAL_DOCUMENTATION.md**.

---

## Contents

1. [Getting started](#1-getting-started)
2. [Who can do what (roles)](#2-who-can-do-what-roles)
3. [The dashboard & navigation](#3-the-dashboard--navigation)
4. [Employees](#4-employees)
5. [Promotions & grade history](#5-promotions--grade-history)
6. [Master data (departments, banks, pension houses, unions)](#6-master-data)
7. [Pay components](#7-pay-components)
8. [Salary tables](#8-salary-tables)
9. [Tax tables (PAYE)](#9-tax-tables-paye)
10. [Uploading monthly earnings & deductions](#10-uploading-monthly-earnings--deductions)
11. [Running payroll](#11-running-payroll)
12. [Payslips](#12-payslips)
13. [Reports](#13-reports)
14. [Change requests & ESS accounts](#14-change-requests--ess-accounts)
15. [The employee self-service portal](#15-the-employee-self-service-portal)
16. [Common tasks (quick recipes)](#16-common-tasks-quick-recipes)
17. [Troubleshooting](#17-troubleshooting)

---

## 1. Getting started

**Signing in.** Open the site and click **Staff log in**. Enter your email and password. There is no public sign-up — accounts are created for you by HR/Admin. If you forget your password, use **Forgot password** on the login screen.

**Home page.** The landing page shows the institution branding and a button into the system. After signing in you land on your dashboard (back-office staff) or the ESS portal (regular staff).

---

## 2. Who can do what (roles)

| You are… | You can… |
|---|---|
| **Administrator** | Everything. |
| **HR** | Manage employees, record promotions, manage master data, review change requests, invite ESS accounts, upload earnings/deductions. |
| **Bursary** | Run payroll, manage pay components, salary tables and tax tables, upload earnings/deductions, produce reports. |
| **Auditor** | View employees, payroll and reports (read-only). |
| **Employee** | View your own payslips and request changes to your record. |

The left-hand menu only shows what your role can use.

---

## 3. The dashboard & navigation

The **sidebar** on the left is your main menu. Typical items: Dashboard, Employees, Payroll, Upload earnings, Upload deductions, Change requests, ESS accounts, Master data, Pay components, Salary tables, Tax tables. Your user menu (bottom left) has settings and sign-out.

Green/red banners at the top of a page confirm an action succeeded or explain why it didn't.

---

## 4. Employees

### Viewing employees
Go to **Employees**. Search by **file number, IPPIS number or name**, and filter by structure or department. Click a name to open their profile.

### The employee profile
Shows Personal details, Bank & Pension, Latest payslip, **Grade & promotions**, and their **Earnings/allowances** and **Voluntary deductions** enrolments.

### Adding an employee (HR/Admin)
1. **Employees → New employee.**
2. Enter the **File Number** (required — the primary staff identifier). **IPPIS Number** is optional (add it when assigned).
3. Enter the name, then choose **Salary structure → Grade → Step** (these cascade — pick the structure first).
4. Fill in Department, employment status, personal details, **Bank** and **Pension house** (both are selectable lists), and Union.
5. **Save.** An initial grade record is created automatically for the promotion history.

### Editing an employee
Open the profile → **Edit**. Change any field and Save. If you change the grade/step directly here, it's logged to the promotion history as a **Correction** (for proper promotions use *Record promotion* — see §5).

### Importing employees in bulk
**Employees → Import.** Download the template, fill it in, upload it. Rows are matched by **File Number** (re-uploading updates existing staff). The result shows created/updated/skipped counts with any problem rows listed.

---

## 5. Promotions & grade history

The system keeps a **dated history** of every employee's grade, and payroll uses the grade that was in force for each month.

### Recording a promotion (HR/Admin)
1. Open the employee → **Grade & promotions** card → **Record promotion**.
2. Choose the **Type**: Promotion, Increment (annual step), Conversion (structure change), Demotion, or Correction.
3. Set the **Effective from** date. This can be:
   - **Today or a past date** — takes effect immediately (and back-dated months recalculate correctly).
   - **A future date** — it's **scheduled** and activates automatically on that date.
4. Choose the new **Structure → Grade → Step** (cascading).
5. Optionally add a **Reference** (promotion letter number) and **Reason/notes**.
6. **Record.**

### How it affects pay
- The change flows through automatically to base pay, and therefore to pension, NHF and PAYE, for the affected month.
- **Recalculate** the relevant payroll run to apply it. If the run is already Approved/Paid/Closed, it's locked — the change applies to future runs.
- The timeline shows every entry with its type, effective date, reason and who recorded it. Future entries are tagged **scheduled**. You can remove an entry (except the original) with the **Remove** link.

> Example: recording a promotion effective 1 July means July's payroll uses the new grade, while a re-run of June still uses the old grade.

---

## 6. Master data

Manage the selectable lists used across the system: **Departments, Banks, Pension houses, Unions**.

**Master data** (HR/Admin) opens a tabbed screen — one tab per list.

- **Add** — click *Add …*, type the name, save. It becomes selectable on the employee form.
- **Edit** — renaming a bank/pension house/union updates every employee record that used it.
- **Delete** — blocked while any employee still uses it (you'll be told how many). Reassign them first, or set the item **Inactive** to hide it from new selections without deleting.
- **Import** — each tab has an **Import** button: download the *Name / Active* template, fill it, upload. Existing names are updated, not duplicated.

---

## 7. Pay components

**Pay components** (Bursary/Admin) defines every earning, deduction and statutory item.

- **Type** — Earning, Deduction or Statutory.
- **Calculation method** — Fixed amount, Percent of a base, Grade table (base salary), etc.
- **Treatment** (shown per type):
  - Earnings: **Taxable** (adds to the PAYE base) and **Pensionable**.
  - Deductions: **Tax-exempt (reduces PAYE)** — tick this for NHIS and life-assurance premiums so they lower taxable income.
  - Statutory (pension/NHF/PAYE) are computed by the engine — no treatment to set.
- **Code** is fixed once created; **Active** controls whether it's available.

To create a new allowance or deduction, add it here, then enrol employees (on their profile) or upload monthly amounts (§10).

---

## 8. Salary tables

**Salary tables** (Bursary/Admin) holds the pay scale: for each **structure → grade → step**, the **consolidated amount**. These are effective-dated, so a scale change from a date doesn't alter past payroll. You can import a scale from the provided template. Base pay for every employee comes from here, based on their current grade.

---

## 9. Tax tables (PAYE)

**Tax tables (PAYE)** (Bursary/Admin) makes the PAYE calculation fully configurable — no code changes.

Each tax table has:
- **CRA relief** — the ₦200,000 fixed floor, the 1%-of-gross alternate floor, and the 20% add-on.
- **Minimum tax** — a % of gross that tax can't fall below (per the Sixth Schedule).
- **Graduated bands** — add/edit/remove rows (band width in ₦, rate in %); leave the **last** band's width blank for the open-ended "and above" rate.
- **Effective dates** — each table applies from its date, so old runs reproduce their original figures and a new tax law is just a new table.

Values are entered as percentages (e.g. `7`, `11`, `20`) and stored precisely.

> To temporarily disable minimum tax, set it to `0`.

---

## 10. Uploading monthly earnings & deductions

Use this to apply an allowance or a deduction (e.g. **SSUCOEN Loan**) to many staff at once for a specific month.

**Upload earnings** or **Upload deductions** (HR/Bursary):

1. Choose the **earning/deduction** and the **month**.
2. **Download the template** — two columns: **File Number**, **Amount** (a header row is optional).
3. Fill it in and **upload**. Each row looks up the employee by file number and sets their amount for that month.
4. Review the result: **applied** and **skipped** counts, with unknown file numbers and bad amounts listed back.
5. **Recalculate that month's payroll run** to reflect the amounts.

**How the amounts behave:**
- They apply to the **selected month only** and **override** any standing amount, then **clear automatically** the next month.
- Staff **not** in the file are left unchanged.

**Standing vs upload-only.** If the chosen item still has a *standing* amount for some staff (applies every month), an amber notice appears with a **Make upload-only** button. Clicking it stops the standing amounts so the item deducts/pays **only in months you upload**. Past payslips are never affected.

---

## 11. Running payroll

**Payroll** (Bursary/Admin) lists all runs with their status and totals.

### Create / calculate a run
1. **Payroll → New run** (or the create control): enter the **period** (YYYY-MM) and the **ruleset** (PITA).
2. The run starts **Processing**; the page updates itself as it calculates, then shows **Calculated**.

### Review
The run page shows headline totals (employees, gross, statutory, voluntary, net), a **by-structure summary**, and the list of **payslips** (searchable by file number, IPPIS or name).

### Approve → Pay → Close
A run moves through statuses:
- **Calculated** → **Approve** (locks it — becomes immutable) → **Mark paid** → **Close.**
- While unlocked you can **Recalculate** (after uploading amounts or recording promotions) or **Delete**.
- Once **Approved/Paid/Closed** the run can't be changed — this protects paid figures.

> Recalculate whenever you've uploaded new deductions/earnings or recorded promotions for that month.

---

## 12. Payslips

From a run, click a name to open a payslip. It shows identity, grade, bank/pension, all earnings and deductions, taxable income, PAYE and net pay. Use **Download PDF** for an individual payslip. Bulk payslips for a whole run are produced under Reports (§13).

---

## 13. Reports

On a **calculated run**, the **Reports (PDF)** card offers the official reports.

**Instant downloads** (open immediately):
- **Departmental summary** — staff/gross/deductions/net per department.
- **Banks summary** — the same, grouped by bank.
- **Pension (PFA) summary** — employee + employer + total per PFA.
- **Payroll journal** — double-entry journal with amount-in-words.
- **Payment vouchers** — one voucher per third-party payee.
- **Yearly summary** — month-by-month totals for the year.

**Large reports** (generated in the background — click to build, then download when ready):
- **Departmental listing** — the full register grouped by department.
- **Deductions schedules** — per-member lists for every deduction (coops, loans, fees, union dues).
- **PFA schedules** — per-member remittance list for each pension house.
- **Departmental payslips** — printable payslips for the whole run.

For a large report, click its button to **Generate**; it shows a spinner while the system builds it, then becomes a **Download** button. (A background worker must be running — see Troubleshooting.)

**Pay Record Card.** On an employee's profile, the **Pay Record Card** control builds a per-year card (also generated in the background).

---

## 14. Change requests & ESS accounts

**Change requests** (HR/Admin) lists updates staff have requested to their own records (e.g. bank or phone). Review each and **Approve** or **Reject**.

**ESS accounts** (HR/Admin) is where you give staff portal access:
- Set an employee's **email**, then **Invite** them. They receive a signed link to set their password and activate their account.

---

## 15. The employee self-service portal

Regular staff sign in and land on the **portal**:
- **Home / Profile** — view their details.
- **Payslips** — view and download their payslips (only for approved-or-later runs).
- **Requests** — submit a change request to their record for HR to review.

---

## 16. Common tasks (quick recipes)

**Add a new allowance and pay it to some staff this month**
1. Pay components → create the earning (Type = Earning, Fixed).
2. Upload earnings → pick it, pick the month, upload File Number/Amount.
3. Payroll → open/recalculate the month's run.

**Process a monthly loan schedule (e.g. SSUCOEN)**
1. Upload deductions → pick the loan, pick the month, upload the sheet.
2. If it should only deduct when uploaded, click **Make upload-only** once.
3. Recalculate the month's run.

**Promote an employee from July**
1. Employee → Grade & promotions → Record promotion → Type *Promotion*, Effective *1 July*, new grade/step.
2. Recalculate July's run (if not yet approved).

**Correct a wrong bank name for everyone**
1. Master data → Banks → Edit the bank → fix the name (it updates all employees using it).

**Change the brand colour**
- Set `PAYROLL_BRAND_COLOR` (e.g. `#0055AA`) in the environment; ask IT to clear the config cache. No rebuild needed.

---

## 17. Troubleshooting

| Symptom | Cause / fix |
|---|---|
| A large report's **Generate** button spins forever | The background worker isn't running. IT must start `php artisan queue:work`. |
| A **payroll run** stays "Processing" | Same — the calculation is a background job that needs a running worker. |
| Uploaded amounts **didn't appear** on payslips | Recalculate the run. If it's Approved/Paid/Closed it's locked — the amounts apply to future runs. |
| Searching a **file number** finds nothing | Search matches file number, IPPIS and name; check for stray spaces. |
| A promotion **isn't reflected** in a run | Recalculate the run. Locked runs can't change. Future-dated promotions apply from their date. |
| Can't **delete** a department/bank/etc. | It's still in use. Reassign those staff or mark the item Inactive instead. |
| An employee **has no pay** (unpriced) | Their grade/step isn't in the salary table for the run's date. Fix the salary table or the employee's grade. |
| **PAYE looks wrong** | Check the Tax table's CRA, bands and minimum tax; confirm which table is effective for the run's date. |
```
