backend phase 11

dev/shared-working-context/backend/STATUS.md

@@ -12,6 +12,28 @@ One block per completed backend phase. Newest at the top. Backend lane writes he
 - **Notes for frontend:** <anything load-bearing>
 -->
 
+## backend-phase-11 — Refunds, invoices & nurse clawbacks — 2026-07-09
+- **Shipped:** the reversal leg via one migration in the **`payments`** schema — **3 tables** `Refunds`
+  (fee-leg decomposition + `refund_channel` + `amount = fee_leg + payout_leg` CHECK + **nullable `ticket_id`, no FK**
+  until b15) / `NurseClawbacks` (nullable `original_payout_id`/`recovered_in_payout_id` until b13) / `Invoices`
+  (**UNIQUE `invoice_number`** sequential + UNIQUE `booking_id`), plus the `InvoiceNumberSequences` counter row.
+  Features: `CreateRefund` (whole money-path under `lock(booking:{id}:refund)`; decompose → Σ≤captured → channel →
+  balanced ledger reversal via b10's helper; pre-payout `nurse_payable` vs post-payout `nurse_clawback_receivable`
+  fork + `pending` clawback + support alert), `WriteOffClawback`, `ListRefunds`, `GetRefundStatus`, `IssueInvoice`
+  (VAT on commission only from config, sequential number, mocked مودیان), `GetInvoice`. Controllers: admin
+  `AdminRefunds`/`AdminClawbacks`/`AdminInvoices` (rate-limited) + customer `Refunds`/`Invoices`.
+- **Contracts:** dev/contracts/domains/refunds-invoices.md + openapi snapshot refreshed — **yes**.
+- **Mocked:** `IMoadianClient` (new), `IBnplProvider` (thin pre-b12 stub), `INursePayoutStatus` (interim derivation;
+  b13 owns real); reused `IPaymentProvider`/`IWebhookVerifier`/`IDistributedLock`/`INotificationDispatcher`. See
+  reports/mocks-registry.md.
+- **Gate:** build clean (0 new warnings) / tests green (300 pass: 205 Foundation + 91 Api + 4 Identity). Migration
+  applied to the dev DB; swagger snapshot republished.
+- **Handoff:** backend/handoff/after-backend-phase-11.md
+- **Notes for frontend:** refunds are **admin-only** (no self-service); the only customer surfaces are
+  `GET refunds/{id}/status` (with the BNPL `expected_customer_refund_eta` date + masked reference) and
+  `GET invoices/{booking_id}`. Money is IRR digit-strings. Card refund = immediate `succeeded`; BNPL = `processing`
+  + ETA.
+
 ## backend-phase-10 — Payments core: ledger, transactions, webhooks & card capture — 2026-07-06
 - **Shipped:** the money core via one migration in a new **`payments`** schema — **4 tables** `PaymentGateways`
   (encrypted `config_json`) / `PaymentTransactions` (the **two filtered uniques** — `gateway_reference_code` WHERE