# Domain 7 — Payouts to Nurses

← Database Model

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`.

↑ Back to top