hamid/baya-monorepo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

clean and refine product docs structure

Browse Source
This commit is contained in:
hamid
2026-06-24 01:32:46 +03:30
parent be07c703ec
commit 1df3cd9f64
113 changed files with 6078 additions and 4973 deletions
Download Patch File Download Diff File Expand all files Collapse all files
product/data-model/07-payouts.md
+23
View File
@@ -0,0 +1,23 @@
# Domain 7 — Payouts to Nurses
[← Database Model](index.md)
**Related:** business requirements — [Payouts](../business/10-payouts.md).
### `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`.