Reservation

1. Overview

Property	Value
ID	FEAT-SALE-RES
Status	Stable
Owner	sale-team
Depends on	AllocationUnit, AllocationUsage, SaleOrder (post check-in), Customer (optional)

Reservation captures a future booking with guest details, party size, and time window. Creating a reservation also creates one or more AllocationUsage rows (status ACTIVE) holding the unit(s) until check-in or cancellation. On check-in, sale spawns a SaleOrder and re-targets the usage rows.

2. Entity Model

Field details — see Domain Model §3.6.

3. Lifecycle

From	Event	To	Side effect
PENDING	confirm	CONFIRMED	optional notification
CONFIRMED	check-in	CHECKED_IN	create SaleOrder, retarget AllocationUsage to usageType=SALE_ORDER
* (non-terminal)	cancel	CANCELLED	cascade cancel AllocationUsage
CONFIRMED	reservedTo elapsed	(manual)	sweep job marks AllocationUsage.EXPIRED

4. Operations

ReservationService (reservation.service.ts — 686 lines).

Method	Signature	Purpose
create	{ context, data: TCreateReservationRequest } (line 112)	Reservation + AllocationUsage rows in one TX
checkIn	{ id, ... } (line 423)	CONFIRMED → CHECKED_IN; spawn SaleOrder
cancel	{ id, cancellationReason? } (line 340)	non-terminal → CANCELLED + cascade

No dedicated confirm service method or REST endpoint today. PENDING → CONFIRMED transition is performed via CRUD updateById with status: CONFIRMED (handled by MerchantScopedService inheritance).

5. REST Endpoints

Verb	Path	Auth	Permission	Handler
6× CRUD	/reservations	JWT/BASIC	Reservation.<crud>	merchant-scoped (covers create + status updates)
POST	/reservations	JWT/BASIC	Reservation.create	ReservationService.create (with allocation in same TX)
POST	/reservations/:id/check-in	JWT/BASIC	Reservation.checkIn	checkIn
POST	/reservations/:id/cancel	JWT/BASIC	Reservation.cancel	cancel

No /confirm endpoint — confirmation is via CRUD PATCH /reservations/:id with { status: 'CONFIRMED' }.

Live OpenAPI: /v1/api/sale/doc/openapi.json.

6. Events

Outbound (WebSocket):

Topic	When	Action enum
observation/sale/reservation	create	RESERVATION_CREATED
same	confirm	RESERVATION_CONFIRMED
same	cancel	RESERVATION_CANCELLED
same	check-in	RESERVATION_CHECKED_IN
observation/allocation/allocation-usage	create/cancel/check-in	USAGE_CREATED / USAGE_CANCELLED

Rooms via getReservationRooms (merchant + reservation + allocation unit/zone hierarchy).

7. Related Pages

• Allocation Usage
• Sale Order — created on check-in
• Domain Model