PRD: Đặt bàn
| Module | Đơn hàng (CORE-07) | PRD ID | PRD-RSV-001 |
| Status | Shipped | Owner | Orders squad |
| Date | 2026-05-29 | Version | v1.0 |
| Packages | @nx/sale · apps/sale-renderer · apps/sale-main | URD | RSV |
TL;DR
Cho phép một nhà hàng full-service nhận đặt bàn trước giờ phục vụ - khách, số khách, ngày/giờ, bàn/phòng - đưa qua một vòng đời đặt chỗ rõ ràng, và biến một lượt đặt thành đơn hàng đang chạy khi check-in mà không phải nhập lại. Floor view và tình trạng zone luôn đồng bộ theo thời gian thực, nên host luôn biết bàn nào đang được giữ, đã xác nhận hay đã ngồi.
1. Context & Problem
Các nhà hàng F&B full-service nhận đặt bàn trước giờ phục vụ: host ghi lại khách, số khách, và ngày/giờ, rồi xếp chỗ cho nhóm khi họ đến. Luồng đơn hàng của KICKO chưa có một thực thể đặt chỗ hạng nhất, nên một lượt đặt trong tương lai và đơn hàng sau đó của nó bị tách rời - host phải nhập lại đơn tại bàn, việc giữ chỗ trên một zone/unit là vô hình, và floor view không thể hiển thị bàn nào đang được đặt so với đã ngồi. Điều này chặn quy trình host mà một nhà hàng full-service phụ thuộc vào, và khiến việc theo dõi mức sử dụng bàn trở nên bất khả thi.
Tính năng này giới thiệu một thực thể Reservation trong @nx/sale với vòng đời riêng, metadata nguồn/dịp, và việc giữ zone/unit (bàn/phòng) thông qua mô hình allocation-usage, kết nối lượt đặt với đơn hàng đang chạy khi check-in.
2. Goals & Non-Goals
Goals
- Một thực thể reservation ghi lại tên khách, số điện thoại, số khách, và ngày/giờ, scope theo merchant.
- Một vòng đời đặt chỗ:
PENDING → CONFIRMED → CHECKED_IN / CANCELLED. - Theo dõi nguồn (điện thoại, khách vãng lai, online, khác) và gắn dịp (sinh nhật, kỷ niệm, công việc, v.v.).
- Tự sinh và liên kết một sale order khi check-in, để lượt đặt trở thành đơn hàng đang chạy mà không phải nhập lại.
- Giữ zone/unit (bàn/phòng) qua snapshot allocation usage, với cập nhật socket theo thời gian thực tới floor view.
Non-Goals
- Quản lý sơ đồ bàn / xếp chỗ - Planned, tách khỏi việc đặt chỗ.
- Một ứng dụng màn hình bếp chuyên dụng.
- Order template và theo dõi đơn giao hàng.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Loại bỏ nhập lại | 100% reservation đã check-in sinh và liên kết một sale order (không tạo đơn thủ công tại bàn) |
| Độ chính xác floor | Tình trạng zone/unit phản ánh các lượt giữ chỗ đang hiệu lực, không còn bản ghi cũ |
| Đồng bộ thời gian thực | Cập nhật reservation và zone lan tới floor view qua socket trong phiên đang chạy |
| Tỉ lệ chuyển đổi đặt chỗ | Tỉ lệ reservation đã CONFIRMED đạt tới CHECKED_IN tăng dần theo từng merchant |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng |
|---|---|
| Host | Nhận và quản lý lượt đặt, giữ đúng bàn, check-in khách |
| Cashier | Tiếp tục đơn hàng được sinh từ check-in mà không phải nhập lại |
| Manager / Owner | Thấy việc giữ bàn và hoạt động đặt chỗ trên floor view |
Core scenarios: một host tạo reservation cho khách (số khách, ngày/giờ, bàn) → xác nhận → khi khách đến thì check-in nhóm khách → một sale order được sinh ra và liên kết, lượt giữ bàn được ghi nhận, và floor view cập nhật trực tiếp.
5. User Stories
- Là một host, tôi muốn tạo một reservation với tên khách, số điện thoại, số khách, và ngày/giờ, để lượt đặt được ghi nhận theo merchant.
- Là một host, tôi muốn xác nhận hoặc huỷ một lượt đặt, để vòng đời của nó phản ánh điều thực sự sẽ diễn ra.
- Là một host, tôi muốn gắn nguồn và dịp của một lượt đặt, để nhà hàng có thể chuẩn bị và báo cáo theo đó.
- Là một host, tôi muốn giữ một bàn/phòng cụ thể cho một lượt đặt, để floor view hiển thị nó là đã được đặt.
- Là một host, tôi muốn check-in sinh và liên kết một sale order, để đơn của nhóm khách đã ngồi tiếp tục từ lượt đặt mà không phải nhập lại.
- Là một manager, tôi muốn floor view và tình trạng zone cập nhật theo thời gian thực, để việc giữ chỗ và xếp chỗ luôn hiện hành.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Tạo một reservation với tên khách, số điện thoại, số khách, và ngày/giờ, scope theo merchant | URD-RSV-001 |
| FR-2 | Vòng đời PENDING → CONFIRMED → CHECKED_IN / CANCELLED | URD-RSV-002 |
| FR-3 | Theo dõi nguồn: điện thoại, khách vãng lai, online, khác | URD-RSV-003 |
| FR-4 | Gắn dịp: sinh nhật, kỷ niệm, công việc, v.v. | URD-RSV-004 |
| FR-5 | Khi check-in, sinh và liên kết một sale order tới reservation | URD-RSV-005 |
| FR-6 | Gắn bàn/phòng (zone/unit) qua snapshot allocation usage; lọc theo unitId và zoneId | URD-RSV-001 |
| FR-7 | Socket fan-out theo thời gian thực cho reservation usage và zone để giữ floor view và tình trạng zone trực tiếp | URD-RSV-002 |
Toàn văn requirement và tiêu chí nghiệm thu nằm ở Orders URD. PRD này tham chiếu chúng thay vì viết lại.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | Một reservation đã check-in và sale order được liên kết của nó được ghi cùng nhau; allocation usage được snapshot để một lượt giữ chỗ không bao giờ bị mất |
| Tenancy & authz | Mọi thao tác scope theo merchant (x-merchant-id); các hành động reservation được gate bằng permission |
| Performance / scale | List/lọc SaleOrder + Reservation dùng truy vấn được tối ưu; createdAt được phơi ra để sắp xếp danh sách |
| Real-time | Thay đổi reservation usage/zone phát socket event tới floor view trong phiên |
| i18n | Nhãn/trạng thái hiển thị cho người dùng là song ngữ ({ en, vi }) |
8. UX & Flows
Các bề mặt front-of-house nằm trong apps/sale-renderer (Reservation Sheet, màn hình chi tiết, tạo-từ-danh-sách, chỉnh ngày/giờ, socket listener); một ReservationService/pub Tauri nằm trong apps/sale-main.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Reservation | Lượt đặt - thông tin khách, số khách, ngày/giờ, nguồn, dịp, status, sale order liên kết tùy chọn |
| Allocation usage | Bản ghi snapshot giữ zone/unit (bàn/phòng) được đặt cho reservation |
SaleOrder | Được sinh và liên kết khi check-in để lượt đặt trở thành đơn hàng đang chạy |
Chỉ ở mức khái niệm - schema và bất biến đầy đủ nằm trong sale domain model.
10. Dependencies & Assumptions
Depends on
- Sale Order (URD-ORD) - check-in sinh và liên kết một sale order.
- Mô hình allocation zone/unit - việc giữ bàn/phòng dùng snapshot allocation-usage.
- Lớp socket thời gian thực - floor view và tình trạng zone được giữ trực tiếp qua socket fan-out.
Assumptions
- Merchant định nghĩa zone/unit (bàn/phòng) mà một reservation có thể giữ.
- Một host vận hành bề mặt front-of-house trong
apps/sale-renderer/apps/sale-main.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Một lượt giữ chỗ có thể lệch khỏi lượt đặt khi lỗi một phần | Allocation usage được snapshot cùng reservation; check-in ghi lượt đặt + sale order cùng nhau |
| Chưa có quản lý sơ đồ bàn / xếp chỗ | Ngoài phạm vi đợt này; reservation giữ một zone/unit nhưng sơ đồ là Planned |
| Tình trạng zone cũ nếu một socket event bị bỏ lỡ | Floor view đối soát theo fan-out reservation usage/zone; xem lại nếu phát hiện lệch |
| Huỷ sau khi đã giữ chỗ | Vòng đời hỗ trợ CANCELLED với batch complete/cancel usage để giải phóng lượt giữ chỗ |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 (mở rộng F&B) - xem Orders URD feature catalog |
| Rollout | Mọi merchant F&B; không feature flag |
| Migration | Entity mới; các cột allocation-usage được mở rộng cho binding zone/unit |
| Launch criteria | Create → confirm → check-in được kiểm tra end-to-end; sale order được sinh và liên kết; lượt giữ zone và socket fan-out được kiểm tra trực tiếp |
| Monitoring | Số lượng reservation mỗi merchant, tỉ lệ chuyển đổi check-in, tính nhất quán lượt giữ zone, phân phối socket fan-out |
13. FAQ
Check-in có tạo đơn tự động không? Có - check-in một reservation sẽ sinh và liên kết một sale order, để đơn của nhóm khách đã ngồi tiếp tục từ lượt đặt mà không phải nhập lại.
Một reservation có thể giữ một bàn hoặc phòng cụ thể không? Có - một reservation gắn một zone/unit qua một snapshot allocation usage; danh sách có thể lọc theo unitId và zoneId.
Điều gì xảy ra với lượt giữ bàn nếu một lượt đặt bị huỷ? Vòng đời hỗ trợ CANCELLED với batch complete/cancel usage, giải phóng zone/unit đang được giữ.
Tính năng này có bao gồm quản lý sơ đồ bàn kéo-thả không? Không - quản lý sơ đồ bàn / xếp chỗ là Planned và tách khỏi việc đặt chỗ; tính năng này giữ một zone/unit nhưng không quản lý sơ đồ floor.
Floor view luôn hiện hành bằng cách nào? Thay đổi reservation usage và zone phát socket event, giữ floor view và tình trạng zone trực tiếp trong phiên.
References
- URD: Orders - Reservations
- Builds on: Sale Order
- Module: Đơn hàng - tổng quan + traceability
- Developer: @nx/sale · domain model