Domain 7 — Payouts to Nurses
Related: business requirements — Payouts.
nurse_payout_batches [CORE]
Role: Weekly aggregation of amounts owed for completed, payout-eligible, unpaid bookings/sessions. Why batched: matches the operational rhythm and the PAYA settlement cycle; an admin (or scheduled job) initiates it. Holiday-aware: period_end/processing dates shift off bank-closed days using iranian_holidays (a weekly payout landing on a multi-day Nowruz closure would otherwise fail). Fields unchanged: period, total_amount, payout_count, status, initiated_by_admin_id, processed_at, failure_notes, timestamps. CHECK: total_amount = Σ payouts. Relations: 1:N → nurse_payouts.
nurse_payouts [CORE]
Role: One row per nurse per batch — the exact amount transferred, the IBAN snapshot, and the bank transfer reference. Why these additions: a batch must be able to net prior clawbacks so it doesn't overpay a nurse who owes money back.
| Field | Type | Notes |
|---|---|---|
| baseline | … | id, batch_id, nurse_id, bank_account_id, iban_snapshot (enc), amount, booking_count, status, transfer_reference, paid_at, failure_reason, created_at |
gross_earnings_irr | BIGINT | NEW — sum of eligible session/booking payouts |
clawback_applied_irr | BIGINT | NEW — clawbacks netted this batch |
net_amount_irr | BIGINT | NEW — gross_earnings − clawback; amount = actually transferred net |
Relations: N:1 → nurse_payout_batches, nurse_profiles, nurse_bank_accounts; 1:N → nurse_payout_booking_links; referenced by nurse_clawbacks.
nurse_payout_booking_links [CORE]
Role: Join from a payout to the specific bookings it covers, with booking_id UNIQUE to guarantee a booking is paid in exactly one batch. Why: per-booking reconciliation and the structural anti-double-pay guard (the previous model's strongest correctness feature — kept). Fields unchanged. Relations: N:1 → nurse_payouts; 1:1 → bookings.