refinement phase 3

2026-07-13 11:26:39 +03:30
parent 1ce36f9414
commit 314763f764
194 changed files with 24211 additions and 274 deletions
@@ -125,3 +125,24 @@ ISO-8601; `expected_customer_refund_eta` is a **date** (`"2026-08-24"`).

 ## Changelog
 - b11 — initial contract (create refund, list refunds, write-off clawback, issue invoice, refund status, get invoice).
+
+---
+
+## Refinement phase 3 additions (REQ-019/020/021 — customer refunds)
+
+- **`POST api/v1/bookings/{id}/cancel`** (customer) — cancels the booking (freezing the policy snapshot) AND
+  opens its refund in one call → `RefundStatusDto`. Body `{ reasonCategory, reasonNotes?, sessionIds? }`
+  (MVP cancels all un-started sessions; `sessionIds` is accepted for forward-compat).
+- **`GET api/v1/bookings/{id}/cancellation_policy`** (customer) — pre-cancel disclosure: resolves the
+  applicable policy by **current** lead time + per-session refundability →
+  `{ bookingId, cancellable, cancellationPolicyCode, refundPercentageApplied, feePercentage, refundAmountIrr,
+  feeAmountIrr, refundableAmountIrr, platformFeeRefundedIrr, nursePayoutRefundedIrr, appliesTo, leadTimeLabel,
+  refundChannel, expectedCustomerRefundEta (null in preview), sessions: [{ bookingSessionId, sessionIndex,
+  scheduledDate, refundable, reasonCode }] }`. `refundAmountIrr + feeAmountIrr = refundableAmountIrr`.
+- **`GET api/v1/refunds/by_booking/{bookingId}`** (customer) — the booking's latest refund status (404 if none).
+- **`RefundStatusDto`** gains `platformFeeRefundedIrr`, `nursePayoutRefundedIrr`, `refundPercentageApplied`,
+  `cancellationPolicyCode`, `createdAt`, `completedAt` (the fee-leg transparency split).
+- **Canonical `cancellation_policy_code` set** (seeded, stable — the frontend's `free_24h`/`partial_under_24h`/
+  `customer_no_show` were invented): **`standard_24h`** (customer ≥24h → full refund), **`standard_inside_24h`**
+  (customer <24h → partial), **`nurse_no_show`** (nurse-initiated → full refund + penalty), **`admin_cancellation`**
+  (admin → full refund). Per-session `reasonCode`: **`un_started`** when refundable, else the blocking session status.