baya-monorepo/archive/build-chain/working-context/backend/handoff/after-refinement-phase-6.md

After refinement-phase-6 — Money-path correctness completion

Track: backend (money path). Gate: dotnet build 0 new warnings · dotnet test 396 pass (+13). Migration RefinementPhase6MoneyFks scaffolded (additive: 3 FK sets + invoice index + delete of a dead config seed row).

What's now live (new endpoints — admin)

• POST api/v1/admin_refunds/{id}/confirm_settlement — settle a processing BNPL/manual refund (processing → succeeded, posts the deferred refund_payable ↔ escrow_held clearing). Idempotent.
• POST api/v1/admin_refunds/{id}/mark_failed — fail a processing refund (no ledger). Body { "reason": "..." } (optional). Idempotent.
• Both return RefundSettlement { refundId, bookingId, status, completedAt }. Contract: dev/contracts/domains/refunds-invoices.md; snapshot swagger.v1.json refreshed.

What changed under the hood (no client-visible shape change)

• The BNPL provider cash-back callback now auto-settles the matching processing refund (a refund/revert completed|confirmed|settled / cashback event) — so a real BNPL revert reaches succeeded without an admin click.
• Refund create persists the row (approved) before the external channel call (crash-window fix) — an interrupted refund is now a reconcilable approved row, not a lost execution.
• Forward-dep FKs added: refunds.ticket_id, nurse_clawbacks.original_payout_id/recovered_in_payout_id, invoices.partner_center_id (+ index). All nullable, NO ACTION. No behavior change; integrity backstop only.
• Audit: Refund/NurseClawback/NursePayout/NursePayoutBatch/NurseVerification are now IAuditable → admin decisions leave an audit_logs diff row (IBAN redacted).
• Retired the orphaned refund_ticket_required config key (a refund ticket is always auto-opened).

Frontend notes

• The customer refund-status flow is unchanged — a BNPL refund still shows processing with the ETA, and now actually flips to succeeded once settled (via admin confirm or the provider callback). No new client work required for the customer side.
• If/when an admin refund console surfaces settlement, the two new endpoints are the actions (staff-gated, sensitive rate policy).