Detailed Functional Requirements
Employee Payroll Profile — Detailed Requirements
What must be true of an employee before they can be paid: the payroll-relevant attributes on the employee master (tax category, children, relief top-up, employment dates, contribution group), the standing item assignments that define pay, and their per-scheme statutory registration numbers (TIN, pension PIN, NHF number). The run reads this data; it never edits it.
3
Data sources
6
Requirements
1
Import flow
Payroll profile
Tax category, children, relief top-up, join/resign dates, contribution group, attendance group.
Item assignments
Catalogue items with an amount and effective window — the source of truth for what gets paid.
Statutory numbers
Per-scheme registration IDs held one per employee per scheme.
Employee · Detailed
Data model
Employee (HR master)
payroll-relevant fields| Field | Type | Notes |
|---|---|---|
basicSalary | number | Fallback base only — the run prefers the basic-salary item assignment. |
taxCategory key | enum | SINGLE / MARRIED_SPOUSE_WORKING / MARRIED_SPOUSE_NOT_WORKING — drives spouse relief. |
numberOfChildren | number (default 0) | × per-child relief from the year's bracket. |
annualPersonalRelief | number (default 0) | Manual additive relief top-up per employee. |
taxResidencyStatus | enum | unused Stored but never read by the tax path. |
joinDate, resignDate key | dates | Drive mid-month proration. |
payrollContributionGroupId key | reference | The statutory policy applied when joining a run. |
payrollItemGroupId | reference | dormant Group membership is stamped on materialised assignments instead. |
attendanceGroupId | reference | Shift schedule → working-day set, days/month, hours/day (defaults Mon–Fri, 30, 8). |
EmployeePayrollItem
standing assignment| Field | Type | Notes |
|---|---|---|
employeeId | reference | Required. |
itemSettingId | reference → catalogue | The item definition supplying all behaviour. |
itemGroupId | reference | Stamped when created by applying an item group. |
amount | number (default 0) | Flat amount — no formulas on the assignment. |
status | enum | ACTIVE (default) / INACTIVE. |
startDate key | date | Required. Effective from. |
endDate | date | Effective until; open-ended when unset. |
EmployeeStatutory
registration numbers| Field | Type | Notes |
|---|---|---|
employeeId + statutoryTypeId key | references | Unique per company + employee + scheme. |
number | string | TIN / pension PIN / NHF number etc. — free text, no format validation. |
Employee · Detailed
Payroll profile EMP-P
FR-EMP-P01Must
The system SHALL hold, per employee, the tax category, number of children, a manual annual relief top-up, join/resign dates, and the contribution-group and attendance-group links — and payroll SHALL read these without modifying them.
Acceptance criteria
- Spouse relief applies only to the married-spouse-not-working category; children multiply the per-child relief.
- An employee with no contribution group produces no statutory contributions.
- Daily rate = gross ÷ working days in the period; overtime hourly rate = gross ÷ days-per-month ÷ hours-per-day from the attendance group (defaults 30 × 8).
Employee · Detailed
Item assignments EMP-A
The standing assignment of a catalogue item — amount plus effective window. Created singly, by import, or by applying an item group.
FR-EMP-A01Must
An assignment SHALL be active for a run when its status is active and the run's pay date falls inside
[startDate, endDate] (open-ended when no end date); the run reads active assignments live at calculate time.Acceptance criteria
- Ending a recurring allowance mid-year only requires setting its end date.
- Salary revisions are modelled by end-dating the old assignment and starting a new one.
FR-EMP-A02Must
An employee SHALL NOT hold two overlapping active assignments of the same catalogue item — enforced on create, import, and item-group apply (which skips rather than fails).
Acceptance criteria
- Open-ended windows are treated as extending indefinitely for overlap purposes.
FR-EMP-A03Must
Annual-frequency amounts SHALL smooth ÷12 at read time; monthly amounts pay as-is.
Acceptance criteria
- A ₦1,200,000 annual allowance contributes ₦100,000 per month.
- There is no one-off frequency and no bonus flag on this instance — a one-time payment is modelled as a monthly item with a single-month window (and is taxed as ordinary pay; see PAYE gaps).
Employee · Detailed
Statutory numbers EMP-S
FR-EMP-S01Must
The system SHALL hold at most one registration number per statutory scheme per employee (TIN for PAYE, pension PIN, NHF/NHIS/NSITF numbers), upserted through a per-employee form listing every seeded scheme.
Acceptance criteria
- Upserting a blank number deletes the record.
- Numbers are identity data only — eligibility never depends on their presence.
Employee · Detailed
Bulk import EMP-M
FR-EMP-M01Should
The assignment import SHALL resolve each row's employee by reference or PIN, the item by name, and optionally a contribution group by name (updating the employee's group link on confirm); it SHALL validate amount, dates, end ≥ start, and the no-overlap rule, previewing per-row errors before anything persists.
Acceptance criteria
- Unresolvable employee/item/group or invalid dates produce row-level errors and leave the row unpersisted.
- Confirmation re-validates and reports success/error counts.
Employee · Detailed
Business rules
- Assignments are the source of truth for pay; the employee's basic-salary field is a fallback only.
- Assignments created via a group carry their group's stamp for traceability, but live independently after apply.
- Join on the 1st is a full month — proration triggers only for later joins or in-month resignations.
- Statutory numbers never gate computation — they exist for reporting and remittance references.
Employee · Detailed
Known gaps
No bank / disbursement details. No bank account, payment method or BVN fields anywhere; payment exists only as a GL credit to a salary-liability account. No bank payment file can be produced.
No salary rate types. All salaries are monthly; hourly/daily-rated staff must be approximated through items and attendance-group derived rates.
No dedicated TIN field on the employee master — tax identification lives only in the per-scheme statutory-number store (or the generic ID field).