refinement phase 3

dev/contracts/domains/payouts.md

@@ -97,3 +97,16 @@ The response envelope is the standard `{ data, … }`; the shapes below are the
 
 ## Changelog
 - b13 — initial contract.
+
+---
+
+## Refinement phase 3 additions (REQ-025 — nurse earnings)
+
+- **`GET api/v1/nurse_payouts/earnings_balance`** → `{ pendingTotalIrr, eligibleTotalIrr, paidTotalIrr,
+  clawbackOutstandingIrr, netPayableBalanceIrr }`. `netPayableBalanceIrr` is the **ledger-derived, SIGNED**
+  nurse_payable balance (may be negative = "owed back"; never clamped); `paidTotalIrr` is lifetime, not in the net.
+- **`GET api/v1/nurse_payouts/earnings?state=&page=&pageSize=`** → `PagedResult<NurseEarningsItem>`; `state`
+  (`pending|eligible|paid|clawback_applied`) is **derived server-side** from `bookings.status` +
+  `dispute_window_ends_at < now` + the payout link + any clawback. Filterable by `state`.
+- **`GET api/v1/nurse_payouts/{id}`** → nurse-scoped payout detail (batch window + covered bookings).
+- **`NursePayoutHistoryDto`** gains `failureReason`.