# 5. Booking & Scheduling

← Business Requirements

## (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.

↑ Back to top