# Reservations

Reservations are the central transaction in Turista. They link a customer (or pending customer) to a unit for a date range.

## Reservation model

`App\Models\Reservation` stores:

- `reservation_number` (unique)
- `customer_type` / `customer_id` (morph to `Customer` or `PendingCustomer`)
- `unit_id`
- `promo_code_id`
- `check_in_date` / `check_out_date`
- `adults_count` / `children_count`
- `payment_status` — `paid`, `partially_paid`, or `unpaid`
- `status` — lifecycle state
- `source` — `online` (customer booking) or `manual` (on-arrival booking)
- `total_price`
- `notes`

## Status lifecycle

```
pending → checked_in → checked_out
    ↓
canceled
```

- **pending** — booked online or manually; awaiting check-in.
- **checked_in** — guest has arrived.
- **checked_out** — stay is complete; no further edits allowed.
- **canceled** — reservation cancelled; availability released.

## Booking channels

### Customer online booking

A verified customer selects a unit and dates. The system checks availability, applies any promo code, calculates the total, and creates a `Reservation` with `source = online` and `status = pending`.

### Owner/employee on-arrival booking

When a guest arrives without a prior booking:

1. **Prepare customer** — `POST /api/v1/reservations/on-arrival/prepare` resolves or creates a registered/pending customer.
2. **Validate reservation** — `POST /api/v1/reservations/on-arrival/validate` creates a `PendingReservation`, holds the dates, and sends an OTP to the customer.
3. **Verify OTP** — `POST /api/v1/reservations/on-arrival/verify` converts the pending reservation into a real `Reservation` with `source = manual`.

## Date changes

Customers and owners can update reservation dates. The service:

1. Checks availability for the new range.
2. Recalculates the total price.
3. Adjusts the invoice and receipt.
4. Handles automatic refunds if the new price is lower.

## Check-in / check-out

Owner/employee users can transition a pending reservation to `checked_in` and later to `checked_out`. Checked-out and canceled reservations cannot be edited or canceled again.

## Companions

The `reservation_companions` table was removed; companion information is stored in `notes` or handled by the client application.

## Key services

- `ReservationService` — create, update, confirm, cancel, recalculate.
- `UnitAvailabilityService` — book, release, block availability dates.
- `ReservationReminderScheduler` — schedule reminder notifications.