From 394f9bdfe4c29bcf76bf45c7c7cad946898c1c1d Mon Sep 17 00:00:00 2001 From: Konrad du Plessis Date: Tue, 24 Mar 2026 21:08:32 +0200 Subject: [PATCH] Update CLAUDE.md with split payslip and team pay schedule docs Document the new split payslip feature, team pay schedule fields, pay period calculation helpers, and backward-compatible process_payment. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4d15133..61c90c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,7 +26,7 @@ core/ — Single main app: ALL business logic, models, views, forms, forms.py — AttendanceLogForm, PayrollAdjustmentForm, ExpenseReceiptForm + formset models.py — All 10 database models utils.py — render_to_pdf() helper (lazy xhtml2pdf import) - views.py — All 17 view functions (~1700 lines) + views.py — All 17 view functions (~1900 lines) management/commands/ — setup_groups, setup_test_data, import_production_data templates/ — base.html + 7 page templates + 2 email + 2 PDF + login ai/ — Flatlogic AI proxy client (not used in app logic) @@ -38,7 +38,7 @@ staticfiles/ — Collected static assets (Bootstrap, admin) - **UserProfile** — extends Django User (OneToOne); minimal, no extra fields in v5 - **Project** — work sites with supervisor assignments (M2M User), start/end dates, active flag - **Worker** — profiles with salary, `daily_rate` property (monthly_salary / 20), photo, ID doc -- **Team** — groups of workers under a supervisor +- **Team** — groups of workers under a supervisor, with optional pay schedule (`pay_frequency`: weekly/fortnightly/monthly, `pay_start_date`: anchor date) - **WorkLog** — daily attendance: date, project, team, workers (M2M), supervisor, overtime, `priced_workers` (M2M) - **PayrollRecord** — completed payments linked to WorkLogs (M2M) and Worker (FK) - **PayrollAdjustment** — bonuses, deductions, overtime, loans; linked to project (FK, optional), worker, and optionally to a Loan or WorkLog @@ -102,6 +102,9 @@ python manage.py check # System check - Payslip Preview modal ("Worker Payment Hub"): shows earnings, adjustments, net pay, **plus** active loans/advances with inline repayment forms. Uses `refreshPreview()` JS function that re-fetches after AJAX repayment submission. Repayment POSTs to `add_repayment_ajax` which creates a PayrollAdjustment (balance deduction only happens during `process_payment()`) - Advance Payment auto-processing: `add_adjustment` immediately creates PayrollRecord + sends payslip when an advance is created. Also auto-creates an "Advance Repayment" adjustment for the next salary cycle. Uses `_send_payslip_email()` helper (shared with `process_payment`) - Advance-to-loan conversion: When an Advance Repayment is only partially paid, `process_payment` changes the Loan's `loan_type` from 'advance' to 'loan' so the remainder is tracked as a regular loan +- Split Payslip: Preview modal has checkboxes on work logs and adjustments (all checked by default). `process_payment()` accepts optional `selected_log_ids` / `selected_adj_ids` POST params to pay only selected items. Falls back to "pay all" if no IDs provided (backward compatible with the quick Pay button). +- Team Pay Schedules: Teams have optional `pay_frequency` + `pay_start_date` fields. `get_pay_period(team)` calculates current period boundaries by stepping forward from the anchor date. The preview modal shows a "Split at Pay Date" button that auto-unchecks items outside the current pay period. `get_worker_active_team(worker)` returns the worker's first active team. +- Pay period calculation: `pay_start_date` is an anchor (never needs updating). Weekly=7 days, Fortnightly=14 days, Monthly=calendar month stepping. Uses `calendar.monthrange()` for month-length edge cases (no `dateutil` dependency). ## URL Routes | Path | View | Purpose |