# 5. Booking & Scheduling

[← Business Requirements](index.md)

## (a) Business requirements
The lifecycle has two phases separated into two tables so each table's invariants stay clean: a **request phase** (no money) and a **booking phase** (always implies captured payment).

**Request → accept → pay → confirm lifecycle:**
1. Customer submits a **booking request** (nurse, patient, variant, address, date/time, requested caregiver gender, customer notes). Status `pending_nurse_response`.
2. The nurse must respond before a **response deadline** (`nurse_response_deadline_at`, computed from config and frozen on the request). The nurse **accepts** → `accepted_awaiting_payment`, or **rejects** → `rejected_by_nurse`, or the deadline passes → `expired_no_response`.
3. On accept, a **30-minute payment window** opens (`payment_deadline_at`). The customer pays within it → a `bookings` row is created (`confirmed`). If the window lapses → `payment_deadline_expired`.

**Single-visit AND multi-session / long-duration engagements must both be representable.** Home nursing is frequently multi-visit: post-surgery daily visits for ten days, month-long nightly or شبانه‌روزی (24h live-in) care. A booking therefore carries a `session_count` and owns **N `booking_sessions`** (one row per scheduled visit), each with its own schedule, its own EVV check-in/out, and its own payout eligibility. A single EVV per booking cannot represent a multi-day engagement, so the engagement-to-session split is the core scheduling model.

**Booking lifecycle:** `pending_payment` → `confirmed` (payment captured) → `in_progress` (first/relevant session check-in) → `completed` (sessions checked out) → optionally `disputed` → `closed`; or `cancelled` before service. Allowed transitions are guarded explicitly so the booking and EVV state machines cannot silently contradict.

**Snapshots:** `variant_snapshot_json` and `address_snapshot_json` freeze the service and address at booking time.

## (b) Iran-specific considerations
- Multi-session and شبانه‌روزی live-in care is the **dominant** elder-care shape in Iran, not a niche — modeling only single visits would fail to represent demand.
- Heavy platform control over multi-visit scheduling **strengthens a worker-misclassification argument** under labor law; this is flagged for counsel, and the platform deliberately keeps the nurse's accept/reject autonomy per request.
- Availability slots/exceptions are **soft guidance only** (informing search), not hard blocks — the nurse still individually accepts or rejects each request, which also fits the Shamsi week and holiday rhythm.

## (c) MVP vs DEFERRED
- **MVP:** request→accept→pay→confirm lifecycle with response deadline + 30-min payment window; single-visit bookings; `booking_sessions` for multi-session/long-duration engagements with per-session EVV and payout; explicit status-transition guards; snapshots; soft availability slots/exceptions.
- **DEFERRED:** open-ended recurring schedules (`recurring_booking_schedules` modeled, inactive — launch is all finite engagements); milestone/progress-payment UX beyond per-session accrual; hard availability-based booking blocks.

## (d) Supporting database entities
`booking_requests` (carries `nurse_response_deadline_at`, `payment_deadline_at`, `required_caregiver_gender`), `bookings` (carries `session_count`, `dispute_window_ends_at`, fee split), **`booking_sessions`**, `booking_care_instructions`, `nurse_availability_slots`, `nurse_availability_exceptions`, `nurse_service_variants`, `patients`, `customer_addresses`.

> **Related:** Data model — [Booking & Scheduling](../data-model/05-booking-and-scheduling.md).