38686-vm/docs/FEATURES.md

FoxFitt LabourPay v5 — Features Guide

A complete guide to every feature in the payroll management system for FoxFitt Construction.

---

1. Dashboard (Home Page)

URL: / (after login)

Admin View

• Outstanding Payments stat card — total unpaid wages with breakdown (wages + additions - deductions)
• Paid This Month stat card — total payments made in current month
• Active Loans & Advances stat card — count and total balance
• Outstanding by Project — breakdown of unpaid amounts per project
• Quick Action buttons — Log Work, Run Payroll, View History
• This Week Summary — count of work logs created this week
• Recent Activity — last 10 work logs with project, date, worker count, supervisor badge
• Manage Resources — tabbed panel (Workers / Projects / Teams) with:
  • Active / Inactive / All filter buttons
  • Toggle switches to activate/deactivate items (AJAX, no page reload)
  • Export Workers CSV button

Supervisor View (simplified)

• My Projects, My Teams, My Workers counts
• This Week Summary and Recent Activity (limited to their own projects/teams)
• No payroll access, no resource management toggles

---

2. Attendance Logging

URL: /attendance/log/ Access: Supervisors and Admins

Features

• Date Range Support — set a start date and optional end date to log multiple days at once
• Weekend Controls — checkboxes to include Saturdays and/or Sundays in date range
• Project Selection — dropdown of active projects (supervisors see only their assigned projects)
• Team Auto-Select — choosing a team auto-checks all its members in the worker list
• Worker Multi-Select — scrollable checkbox list of active workers
• Overtime — dropdown: None, 1/4 Day, 1/2 Day, 3/4 Day, Full Day
• Notes — free text field for any additional info
• Conflict Detection — if any selected worker already has a log on the selected date+project:
  • Warning shown with list of conflicts
  • Two options: "Skip Conflicts" (create only non-conflicting) or "Overwrite Existing"
• Estimated Cost (Admin only) — live-updating card showing: R amount, N workers x M days. Recalculates as selections change. Does not include overtime.

---

3. Work History

URL: /history/ Access: All logged-in users (supervisors see only their projects)

List View

• Table: Date, Project, Team, Workers (count), Supervisor, Amount, Payment Status (Paid/Unpaid badge)
• Filters: Worker dropdown, Project dropdown, Payment Status (All / Paid / Unpaid)
• Filter feedback bar: "Showing X of Y work logs" with active filter badges and clear button
• CSV export button (preserves active filters)

Calendar View

• Monthly grid with previous/next navigation
• Each day shows: work log count badge, first 3 project indicators, "+X more" for overflow
• Colour coding: green checkmark (paid), orange clock (unpaid)
• Today's cell highlighted
• Click a day to see full details in a panel below
• Multi-day selection: click multiple days to see combined totals
• Footer: total days, total logs, unique workers, total amount (admin only)

CSV Export

• Work Logs CSV (/history/export/) — Date, Project, Team, Workers, Supervisor, Worker Count, Daily Cost, Payment Status
• Workers CSV (/workers/export/, admin only) — Name, ID Number, Phone, Monthly Salary, Daily Rate, Employment Date, Active, Notes, Shoe Size, Overall Top Size, Pants Size, T-Shirt Size, Has Drivers License

---

4. Payroll Dashboard

URL: /payroll/ Access: Admin only

Header Buttons

• Worker Lookup — opens modal to view any worker's financial report card
• Batch Pay — pay multiple workers at once based on pay schedules
• Add Adjustment — create bonuses, deductions, loans, advances
• Price Overtime — convert unpriced overtime entries into Overtime adjustments

Analytics Cards

• Outstanding Payments — total unpaid with breakdown (wages + additions - deductions)
• Paid (Last 60 Days) — recent payment total
• Active Loans & Advances — count + total remaining balance
• Outstanding by Project — per-project unpaid amounts

Charts

1. Monthly Payroll — line chart of monthly totals, with toggle to view by individual worker (dropdown selector)
2. Cost by Project — monthly project cost breakdown

Three Tabs

Tab 1: Pending Payments

• Filter Bar:
  • Team dropdown (All Teams or specific team)
  • "Overdue only" checkbox (shows workers with unpaid work from completed pay periods)
  • Loan filter dropdown (All Workers / With loans only / Without loans)
• Table Columns: Worker, Days, Day Rate, Log Amount, Adjustments (colour-coded badges), Net Adj, Total, Actions
• Row Badges:
  • Red "Overdue" — worker has unpaid work from a completed pay period
  • Yellow "Loan" — worker has an active loan or advance
• Action Buttons per Worker:
  • Preview (eye icon) — opens Payslip Preview modal
  • Adjust (slider icon) — opens Add Adjustment modal pre-filled with this worker and their last project
  • Pay (green button) — processes payment for all pending items immediately

Tab 2: Payment History

• Table: Date, Worker, Amount Paid, Work Logs (count), Adjustments (badges), View Payslip link
• Worker names are clickable (opens Worker Lookup modal)

Tab 3: Loans & Advances

• Sub-filter: Active / History toggle buttons
• Table: Worker, Type (Loan/Advance badge), Principal, Balance, Date, Reason, Status (Active/Paid Off)
• Worker names are clickable (opens Worker Lookup modal)

---

5. Payment Processing

Individual Payment

• Click "Pay" on a worker's pending row — processes all unpaid work logs and adjustments
• Creates a PayrollRecord linking the worker, their work logs, and adjustments
• Generates HTML + PDF payslip and emails to Spark Receipt
• Atomic transaction with select_for_update() to prevent duplicate payments

Payslip Preview Modal ("Worker Payment Hub")

• Opened via the Preview (eye) button on pending payments
• Shows: worker name, ID, days worked, day rate, log amount
• Work Logs list with checkboxes (all checked by default) — uncheck to exclude from payment
• Adjustments list with checkboxes — uncheck to exclude
• Split at Pay Date button — auto-unchecks items after the last completed pay period cutoff (useful for paying only what's due)
• Active Loans section — shows outstanding balances with inline repayment forms
• Net Pay total — updates live as items are checked/unchecked
• Pay Selected button — processes only checked items (split payslip)

Batch Pay

• Opened via "Batch Pay" button in header
• Two modes (radio buttons):
  • Until Last Paydate (default) — splits at each worker's last completed pay period; workers without team schedules are skipped
  • Pay All — includes all unpaid items regardless of date
• Team filter — pay only workers in a specific team
• Loan filter (3 options) — All Workers / With loans only / Without loans
• Preview shows list of workers and amounts before confirming
• Processes each worker in independent atomic transactions
• Emails sent after all payments complete

---

6. Payroll Adjustments

Types

Type	Effect	Auto-created?	Details
Bonus	Additive (+)	No	Requires a linked project
Deduction	Deductive (-)	No	Requires a linked project
Overtime	Additive (+)	Yes	Created by "Price Overtime" from unpriced OT entries
New Loan	Additive (+)	No	Creates a Loan record. "Pay Immediately" checkbox (default: checked) auto-processes and emails payslip
Advance Payment	Additive (+)	No	Auto-processed immediately (never sits in pending). Creates Loan + PayrollRecord + emails payslip. Auto-creates an Advance Repayment for next salary
Loan Repayment	Deductive (-)	Yes	Created from payslip preview inline form. Linked to a Loan
Advance Repayment	Deductive (-)	Yes	Auto-created when an advance is paid

Add Adjustment Modal

• Type dropdown, Project (required for some types), Amount, Date, Description
• Worker multi-select with checkboxes (team helper to select all team members)
• "Pay Immediately" checkbox appears for New Loan type (checked by default)

Quick Adjust Button

• Each pending payments row has an "Adjust" button (slider icon)
• Opens Add Adjustment modal with the worker pre-checked and their most recent project pre-selected
• Header "Add Adjustment" button resets modal to clean state

Edit/Delete Adjustments

• Click any adjustment badge in the pending payments table to edit
• Can change type, project, amount, date, description
• Delete button with confirmation modal
• Only unpaid adjustments can be edited/deleted

Price Overtime

• Opens modal showing all unpriced overtime work log entries
• Filter by worker name
• Table: Worker, Date, Project, OT Amount, Day Rate, Total
• Checkboxes to select which entries to price
• Price multiplier input (default 1.5x)
• Creates Overtime-type PayrollAdjustments for selected entries

---

7. Loans & Advances

New Loan Flow

1. Create via Add Adjustment → type "New Loan"
2. "Pay Immediately" checkbox (checked by default):
   • Checked: Creates Loan + PayrollRecord + emails payslip to Spark immediately
   • Unchecked: Creates Loan, sits in Pending Payments for next pay cycle
3. Editing a loan adjustment syncs amount/balance/reason on the Loan record
4. Deleting cascades to Loan + any unpaid repayments

Advance Payment Flow

1. Create via Add Adjustment → type "Advance Payment"
2. Always auto-processed immediately (no pending state)
3. Creates Loan (type='advance') + PayrollRecord + emails payslip
4. Auto-creates an "Advance Repayment" adjustment for next salary cycle
5. Requires at least one unpaid work log (otherwise use New Loan)

Repayments

• From Payslip Preview: Inline form to add repayment against any active loan
• Loan Repayment: Manual deduction linked to a specific loan
• Advance Repayment: Auto-created, deducts from advance balance during payment processing
• Partial Repayment: If an advance is only partially repaid, the Loan's type changes from 'advance' to 'loan' so the remainder is tracked as a regular loan

Loans Tab

• Active loans: shows all current outstanding loans/advances
• History: shows all loans including paid-off ones
• Columns: Worker, Type, Principal, Balance, Date, Reason, Status

---

8. Worker Lookup Modal

Trigger: Click any worker name on the payroll dashboard, or click the "Worker Lookup" button

Report Card Contents

• Identity: Name, ID number, phone, employment date, team, current project + days on project
• Quick Stats (4 cards):
  • Amount Payable (unpaid earnings + net adjustments)
  • Outstanding Loans (total remaining balance)
  • Paid This Month
  • Loans This Year (total principal issued)
• Recent Activity:
  • Last payslip paid (date + amount)
  • Last loan given (date + amount + reason)
  • Last loan repayment (date + amount)
  • Last advance paid (date + amount)
• Active Loans Table (if any): Type, Amount, Balance, Date, Reason
• Paid This Year total
• Sizing & Info: Shoe size, Overall Top, Pants, T-Shirt, Drivers License status, Notes

Features

• Searchable worker dropdown to switch between workers without closing the modal
• Worker names are clickable links throughout the dashboard (Pending Payments, Payment History, Loans tabs)

---

9. Worker Management

Location: Django Admin (/admin/core/worker/) and Dashboard Manage Resources panel

Worker Fields

Section	Fields
Personal Info	Name, ID Number, Phone, Monthly Salary, Employment Date, Active, Notes
Sizing	Shoe Size, Overall Top Size, Pants Size, T-Shirt Size
Documents & License	Photo (image), ID Document (file), Has Drivers License (checkbox), Drivers License (file)

Admin Features

• Fieldsets organise fields into 3 sections
• List view: Name, ID Number, Monthly Salary, Active
• Filters: Active status, Has Drivers License
• Search: Name, ID Number, Phone Number

Dashboard Toggle

• Manage Resources panel on main dashboard
• Toggle switches to activate/deactivate workers (AJAX)
• Active / Inactive / All filter buttons

Computed Properties

• daily_rate = monthly_salary / 20 working days

---

10. Team Pay Schedules

Configuration

• Each team has optional pay_frequency (Weekly / Fortnightly / Monthly) and pay_start_date (anchor date)
• Set via Django Admin (editable directly in the team list view)

How It Works

• pay_start_date is an anchor — the first day of the very first pay period (never needs updating)
• The system steps forward from the anchor to find the current period
• Weekly = 7 days, Fortnightly = 14 days, Monthly = calendar month stepping
• Handles month-length edge cases using calendar.monthrange()

Impact on Features

• Overdue Detection: Workers with unpaid work from completed pay periods get a red "Overdue" badge
• Split at Pay Date: Preview modal button auto-unchecks items after the cutoff date
• Batch Pay (Until Last Paydate): Only pays items within completed pay periods
• Cutoff date = last day of the most recently completed period (includes ALL overdue work)

---

11. Expense Receipts

URL: /receipts/create/ Access: All staff (admin + supervisors)

Form Fields

• Date, Vendor Name, Payment Method (Cash/Card/EFT/Other), Description
• Dynamic Line Items — add/remove rows with Product Name + Amount
• VAT Options — radio buttons: Included (15% extracted) / Excluded (15% added) / None

Live Calculations

• Subtotal, VAT amount, and Total update in real-time as you type
• VAT calculation adjusts based on Included/Excluded selection

On Submit

• Saves ExpenseReceipt + ExpenseLineItems to database
• Generates HTML email + PDF attachment
• Emails to Spark Receipt (spark@sparkreceipthq.com)

---

12. Email & PDF Generation

Payslip Email

• Sent to: Spark Receipt (for record-keeping)
• Content: Worker name, ID, payment date, base pay, all adjustments, net pay
• Attachment: PDF payslip
• Three variants: Regular (work + adjustments), Advance-only, Loan-only

Receipt Email

• Sent to: Spark Receipt
• Content: Vendor, date, payment method, line items, VAT breakdown, total
• Attachment: PDF receipt

Payslip Detail Page

• URL: /payroll/payslip/<id>/
• Print-friendly view of a completed payslip
• Accessible from Payment History tab "View" button

---

13. Authentication & Permissions

Roles

Role	Access
Admin (is_staff or is_superuser)	Full access: payroll, adjustments, resource management, exports
Supervisor (assigned to projects)	Attendance logging, work history (own projects only), expense receipts

Permission Groups (created by setup_groups command)

• Admin — full CRUD on all core models
• Work Logger — add/change/view WorkLog; view-only on Project/Worker/Team

Authentication

• Django built-in auth at /accounts/login/
• All views require login except /import-data/
• Login redirects to dashboard (/)

---

14. Data Exports

Export	URL	Format	Access	Contents
Work Logs	/history/export/	CSV	Supervisor+	Date, Project, Team, Workers, Supervisor, Cost, Status
Workers	/workers/export/	CSV	Admin	Name, ID, Phone, Salary, Rate, Dates, Sizes, License

Both exports respect active filters (work log export preserves filter parameters in URL).

---

15. Setup & Deployment Tools

Feature	URL	Purpose
Import Data	/import-data/	One-time: loads production worker data from JSON fixtures
Run Migrate	/run-migrate/	Applies pending database migrations on production (for when Flatlogic doesn't auto-apply)
Setup Groups	manage.py setup_groups	Creates Admin + Work Logger permission groups
Setup Test Data	manage.py setup_test_data	Populates sample workers, projects, teams, work logs
Import Production Data	manage.py import_production_data	Imports real production data (14 workers)