Đặt chỗ

1. Tổng quan

Thuộc tính	Giá trị
ID	FEAT-SALE-RES
Trạng thái	Stable
Owner	sale-team
Phụ thuộc	AllocationUnit, AllocationUsage, SaleOrder (sau check-in), Customer (tùy chọn)

Đặt chỗ ghi nhận một booking tương lai với chi tiết khách, party size, và time window. Tạo một đặt chỗ cũng tạo một hoặc nhiều row AllocationUsage (status ACTIVE) giữ unit cho đến check-in hoặc hủy. Khi check-in, sale spawn một SaleOrder và chuyển hướng các row usage.

2. Mô hình thực thể

Chi tiết trường — xem Mô hình miền §3.6.

3. Vòng đời

Từ	Sự kiện	Đến	Side effect
PENDING	confirm	CONFIRMED	thông báo tùy chọn
CONFIRMED	check-in	CHECKED_IN	tạo SaleOrder, retarget AllocationUsage thành usageType=SALE_ORDER
* (non-terminal)	cancel	CANCELLED	cascade hủy AllocationUsage
CONFIRMED	reservedTo đã qua	(thủ công)	sweep job đánh dấu AllocationUsage.EXPIRED

4. Vận hành

ReservationService (reservation.service.ts — 686 dòng).

Phương thức	Chữ ký	Mục đích
create	{ context, data: TCreateReservationRequest } (dòng 112)	Reservation + row AllocationUsage trong một TX
checkIn	{ id, ... } (dòng 423)	CONFIRMED → CHECKED_IN; spawn SaleOrder
cancel	{ id, cancellationReason? } (dòng 340)	non-terminal → CANCELLED + cascade

Không có method service confirm chuyên biệt hoặc REST endpoint hôm nay. Transition PENDING → CONFIRMED được thực hiện qua CRUD updateById với status: CONFIRMED (xử lý qua kế thừa MerchantScopedService).

5. REST Endpoints

Verb	Path	Auth	Permission	Handler
6× CRUD	/reservations	JWT/BASIC	Reservation.<crud>	merchant-scoped (bao gồm create + cập nhật trạng thái)
POST	/reservations	JWT/BASIC	Reservation.create	ReservationService.create (với allocation cùng TX)
POST	/reservations/:id/check-in	JWT/BASIC	Reservation.checkIn	checkIn
POST	/reservations/:id/cancel	JWT/BASIC	Reservation.cancel	cancel

Không có endpoint /confirm — xác nhận qua CRUD PATCH /reservations/:id với { status: 'CONFIRMED' }.

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

6. Sự kiện

Outbound (WebSocket):

Topic	Khi nào	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 qua getReservationRooms (merchant + reservation + cây phân cấp allocation unit/zone).

7. Trang liên quan

• Allocation Usage
• Sale Order — tạo khi check-in
• Mô hình miền