Đặ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 lượt đặt trong tương lai kèm thông tin khách, số khách và khung giờ. Việc tạo một đặt chỗ cũng tạo một hoặc nhiều dòng AllocationUsage (trạng thái ACTIVE) giữ chỗ các unit cho đến khi check-in hoặc huỷ. Khi check-in, sale sinh một SaleOrder và trỏ lại các dòng usage sang order đó.

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	Tác dụng phụ
PENDING	confirm	CONFIRMED	thông báo tuỳ chọn
CONFIRMED	check-in	CHECKED_IN	tạo SaleOrder, trỏ lại AllocationUsage sang usageType=SALE_ORDER
* (chưa kết thúc)	cancel	CANCELLED	huỷ đồng loạt AllocationUsage
CONFIRMED	reservedTo đã qua	(thủ công)	job quét đá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 + các dòng AllocationUsage trong cùng một transaction
checkIn	{ id, ... } (dòng 423)	CONFIRMED → CHECKED_IN; sinh SaleOrder
cancel	{ id, cancellationReason? } (dòng 340)	chưa kết thúc → CANCELLED + huỷ đồng loạt

Hiện chưa có method service confirm riêng hay REST endpoint riêng. Chuyển trạng thái PENDING → CONFIRMED được thực hiện qua CRUD updateById với status: CONFIRMED (xử lý nhờ 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 trong cùng transaction)
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