PRD: POS & order bếp
| Module | Bán hàng | PRD ID | PRD-KIT-001 |
| Trạng thái | Sẵn sàng dev | FEAT | KIT · BANA-1430 |
| Epic | — | Plane | BANA-1561 |
| Ngày | 2026-03-23 | Phiên bản | v1.0 |
| Gói | @nx/sale | URD | KIT |
| Surface | Sale · POS | ||
| Phụ trách | Phát Nguyễn | ||
TL;DR
Đẩy món xuống bếp dưới dạng phiếu, định tuyến theo trạm chế biến có tên, và cập nhật tiến độ nấu theo thời gian thực - không reload, không cần hỏi tay. Trạng thái nấu từng món tự đẩy phiếu tiến lên; void-and-resend đảm bảo món đã báo bếp không bao giờ bị sửa tại chỗ.
1. Context & Problem
Module Đơn hàng đã có cart → checkout → thanh toán, nhưng quán F&B phục vụ tại bàn cần thêm nửa còn lại: đưa món xuống bếp, theo dõi tiến độ nấu, và cập nhật màn hình chế biến mà không reload. Hiện không có thực thể nào phía bếp - món chỉ tồn tại trên order, nên bếp không có hàng đợi, không có trạng thái nấu riêng từng món, và không đẩy được trạng thái về khu phục vụ. Với nhà hàng và quán cà phê HKD/SME mà BANA nhắm tới, khoảng trống này chặn quy trình F&B cơ bản nhất - báo bếp, nấu, phục vụ - khiến POS chỉ dùng được như một quầy tính tiền thường.
Increment này xây dựng quản lý order bếp (KDS) trên nền vòng đời đơn hàng hiện có: phiếu được gửi từ một đơn hàng xuống bếp, các trạm có tên để định tuyến, trạng thái nấu theo từng món, và lan truyền trạng thái trực tiếp qua cập nhật real-time.
2. Goals & Non-Goals
Goals
- Gửi các món trong đơn xuống bếp dưới dạng phiếu có các dòng món, với một lần gửi idempotent để một lần báo bếp lặp lại không bao giờ tạo ra phiếu thứ hai (KIT).
- Một vòng đời phiếu đầy đủ (
PENDING → PROCESSING → READY → COMPLETED / VOIDED) và một vòng đời nấu theo từng món (PENDING → COOKING → READY → SERVED / VOIDED). - Tự động đẩy trạng thái - trạng thái phiếu tiến tự động theo trạng thái các món của nó.
- Cơ chế void-and-resend - một món đã gửi sẽ bị void và gửi lại, không bao giờ sửa tại chỗ.
- Các trạm bếp có tên theo từng merchant (STA) - thực thể trạm đã có; các trường định tuyến theo danh mục và máy in cho từng trạm tồn tại trên model nhưng backend chưa dùng đến (trạm để báo bếp do bên gọi chọn, còn in/tự động in là việc của front end).
- Cập nhật thời gian thực tới màn hình bếp và dashboard khi phiếu được tạo / cập nhật / hoàn thành.
- Một thay đổi trạng thái nấu theo từng món phát ra một sự kiện kích hoạt trừ kho phía sau - trong code hiện tại kho được trừ khi một món đạt ready (đánh dấu một món đã phục vụ tự nó không kích hoạt trừ kho).
Non-Goals
- Một ứng dụng màn hình bếp riêng biệt - increment này chỉ giao phần back end cùng POS front end (Dự kiến).
- Luồng hoàn / trả hàng và phần nội tại trừ kho - thuộc về Kho hàng.
- Quản lý sơ đồ bàn / chỗ ngồi (Dự kiến).
- Phiên ca POS (POS) - liệt kê để đầy đủ phạm vi; xử lý phiên không nằm trong increment này.
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Độ tươi thời gian thực | Màn hình bếp phản ánh thay đổi trạng thái mà không cần tải lại thủ công; fan-out real-time mỗi lần tạo / cập nhật / hoàn thành |
| Tính toàn vẹn khi gửi | Không có phiếu trùng cho một lần báo bếp lặp lại (gửi idempotent giữ vững khi retry) |
| Độ chính xác tự đẩy trạng thái | Trạng thái phiếu luôn khớp với tổng hợp trạng thái các món của nó |
| Độ phủ định tuyến | Các món rơi đúng trạm được map theo danh mục sản phẩm (mục tiêu; định tuyến theo danh mục chưa được nối ở backend - trạm báo bếp do bên gọi chọn) |
| Đúng đắn khi phục vụ | Một thay đổi trạng thái nấu kích hoạt trừ kho đúng một lần một cách đáng tin (trong code hiện tại trừ kho khi một món đạt ready) |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Thu ngân | Báo bếp các món trong đơn và thấy khi nào món sẵn sàng phục vụ |
| Nhân viên bếp | Làm việc trên hàng đợi phiếu trực tiếp, đẩy món cooking → ready → served, void món lỗi |
| Quản lý / Chủ | Cấu hình các trạm, định tuyến theo danh mục, và máy in từng trạm |
Quy trình điển hình: thu ngân báo bếp → phiếu hiện trên màn hình trạm → bếp đẩy từng món cooking → ready → served, phiếu tự đẩy trạng thái, khu phục vụ thấy ngay. Món sai thì void và báo lại - không sửa tại chỗ.
5. User Stories
- Là một thu ngân, tôi muốn gửi các món trong đơn xuống bếp bằng một thao tác, để khu bếp nhận phiếu công việc ngay lập tức.
- Là một thu ngân, tôi muốn một lần báo bếp lặp lại là idempotent, để một lần chạm đúp không bao giờ tạo phiếu trùng.
- Là nhân viên bếp, tôi muốn mỗi món mang trạng thái nấu riêng, để tôi theo dõi một phiếu nhiều món một cách chính xác.
- Là nhân viên bếp, tôi muốn phiếu tự đẩy trạng thái theo các món của nó, để tôi không phải duy trì trạng thái phiếu riêng bằng tay.
- Là nhân viên bếp, tôi muốn void và gửi lại một món đã gửi, để các chỉnh sửa không bao giờ ngầm thay đổi một phiếu đang chạy.
- Là một quản lý, tôi muốn định tuyến các danh mục sản phẩm tới các trạm có tên với cấu hình máy in riêng, để mỗi trạm chỉ thấy và in công việc của nó. (Các trường định tuyến và máy in tồn tại trên model trạm nhưng chưa được backend xử lý.)
- Là một thu ngân, tôi muốn trạng thái bếp cập nhật màn hình theo thời gian thực, để khu phục vụ biết khi nào phục vụ mà không phải hỏi.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Gửi các món trong đơn xuống bếp - tạo một phiếu với các dòng món | URD-KIT-001 |
| FR-2 | Gửi idempotent - một lần gửi trùng tạo ra cùng một phiếu | URD-KIT-002 |
| FR-3 | Vòng đời phiếu PENDING → PROCESSING → READY → COMPLETED / VOIDED | URD-KIT-003 |
| FR-4 | Vòng đời nấu theo từng món PENDING → COOKING → READY → SERVED / VOIDED | URD-KIT-004 |
| FR-5 | Trạng thái phiếu tự đẩy theo trạng thái các món của nó | URD-KIT-005 |
| FR-6 | Các thay đổi dùng void-and-resend - món đã gửi không bị sửa tại chỗ | URD-KIT-006 |
| FR-7 | Cờ rush và số thứ tự theo từng đơn để sắp xếp phiếu | URD-KIT-007 |
| FR-8 | Cập nhật thời gian thực tới màn hình bếp và dashboard | URD-KIT-008 |
| FR-9 | Một thay đổi trạng thái nấu phát ra sự kiện kích hoạt trừ kho - trong code hiện tại trừ kho khi một món đạt ready, không phải khi phục vụ | URD-KIT-009 |
| FR-10 | Tạo các trạm có tên theo từng merchant (i18n) | URD-STA-001 |
| FR-11 | Định tuyến các danh mục sản phẩm tới các trạm - chỉ mức mô hình dữ liệu: trường định tuyến theo danh mục tồn tại nhưng backend chưa dùng đến (trạm báo bếp do bên gọi chọn) | URD-STA-002 |
| FR-12 | Cấu hình máy in cho từng trạm với tự động in - chỉ mức mô hình dữ liệu: các trường máy in/tự động in tồn tại nhưng backend chưa dùng đến | URD-STA-003 |
Toàn bộ nội dung yêu cầu và tiêu chí nghiệm thu nằm trong Orders URD. PRD này tham chiếu chứ không lặp lại chúng.
7. Non-Functional Requirements
| Area | Yêu cầu |
|---|---|
| Thời gian thực | Tạo / cập nhật / hoàn thành phiếu fan-out qua cập nhật real-time; POS front end subscribe để nhận trạng thái trực tiếp |
| Idempotency | Việc gửi được keyed để các retry gộp về một phiếu duy nhất; không trùng công việc bếp |
| Tenancy & authz | Mọi thao tác giới hạn trong merchant của chính người dùng; có kiểm soát theo permission |
| Tính toàn vẹn dữ liệu | Trạng thái phiếu luôn là tổng hợp xác định từ trạng thái các món; chỉnh sửa là void-and-resend, không bao giờ sửa tại chỗ |
| Tính nhất quán | Việc gửi và các chuyển trạng thái là transactional; lỗi một phần không để lại phiếu mồ côi |
| i18n | Tên trạm và các trạng thái hiển thị cho người dùng là song ngữ ({ en, vi }) |
8. UX & Flows
Bề mặt chính: các view phiếu bếp nằm trong POS front end, subscribe vào luồng real-time để nhận trạng thái phiếu/món trực tiếp; cấu hình trạm và định tuyến được quản lý theo từng merchant.
9. Data & Domain
| Entity | Vai trò |
|---|---|
| Kitchen ticket | Phiếu được gửi xuống bếp - trạng thái, cờ rush, số thứ tự theo từng đơn, gán trạm |
| Kitchen ticket line | Một dòng phiếu - tham chiếu order item, mang trạng thái nấu riêng |
| Preparation station | Một khu chế biến có tên (i18n); mang các trường định tuyến theo danh mục và cấu hình máy in trên model nhưng backend chưa dùng đến |
Chỉ mang tính khái niệm - schema và bất biến đầy đủ ở sale domain model.
10. Dependencies & Assumptions
Phụ thuộc vào
- Sale Order (URD-ORD) - phiếu được báo bếp từ các order item.
- Danh mục sản phẩm (Sản phẩm) - định tuyến trạm map danh mục tới trạm.
- Kho hàng (Kho hàng) - một thay đổi trạng thái nấu theo từng món kích hoạt trừ kho (trong code hiện tại trừ khi món đạt ready).
- Vận chuyển thời gian thực - để fan-out trạng thái trực tiếp.
Giả định
- Merchant chạy luồng F&B phục vụ đầy đủ (báo bếp), không chỉ quầy tính tiền.
- Các trạm và định tuyến theo danh mục được cấu hình trước khi báo bếp các món.
- Các client (ví dụ POS front end) giữ một subscription real-time đang hoạt động để nhận cập nhật trực tiếp.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Báo bếp trùng tạo ra hai phiếu | Việc gửi là idempotent qua key; các retry gộp về một phiếu |
| Trạng thái phiếu lệch khỏi trạng thái các món | Trạng thái là tổng hợp tự động xác định, không duy trì bằng tay |
| Sửa một món đã gửi tại chỗ | Bị cấm theo thiết kế - void-and-resend là con đường chỉnh sửa duy nhất |
| Bỏ lỡ một cập nhật real-time khiến màn hình cũ | Màn hình subscribe vào tạo / cập nhật / hoàn thành; kết nối lại sẽ đồng bộ lại |
| Chưa có ứng dụng KDS riêng | Back end + bề mặt POS front end giao ngay; ứng dụng KDS độc lập là Dự kiến |
12. Release Plan & Launch Criteria
| Aspect | Kế hoạch |
|---|---|
| Phase | P2 - xem danh mục feature Đơn hàng (KIT, STA Built) |
| Rollout | Tất cả merchant; không feature flag |
| Migration | Các entity bếp mới; không backfill dữ liệu |
| Launch criteria | Báo bếp → phiếu → nấu → ready/phục vụ đã kiểm chứng đầu-cuối; gửi idempotent giữ vững; tự đẩy trạng thái khớp trạng thái các món; cập nhật trực tiếp tới được POS front end; trừ kho kích hoạt từ sự kiện trạng thái nấu (hiện tại khi đạt ready). Định tuyến tự động danh mục→trạm và tự động in từng trạm chưa được nối |
| Monitoring | Số lượng phiếu theo từng merchant, tỉ lệ lỗi / trùng khi gửi, sức khỏe phân phối real-time, tính nhất quán giữa sự kiện trạng thái nấu và trừ kho |
13. FAQ
Một món bếp đã gửi có sửa được không? Không - các món đã gửi không bao giờ bị sửa tại chỗ. Dùng void-and-resend: void món đó và gửi một món mới.
Điều gì xảy ra nếu một lần báo bếp được gửi hai lần? Không có gì bị trùng - việc gửi là idempotent theo key, nên một lần báo bếp lặp lại quy về cùng một phiếu.
Trạng thái phiếu thay đổi như thế nào? Nó tự đẩy theo trạng thái các món của nó; không có trạng thái phiếu riêng duy trì bằng tay.
Phiếu hiện ở đâu? Trên màn hình của trạm được định tuyến trong POS front end, cập nhật trực tiếp qua cập nhật real-time - không cần tải lại. Một ứng dụng KDS riêng là Dự kiến.
Luồng nấu có làm dịch chuyển kho không? Có - một thay đổi trạng thái nấu theo từng món phát ra một sự kiện mà Kho hàng xử lý; trong code hiện tại kho được trừ khi một món đạt ready (trạng thái đã phục vụ tự nó không kích hoạt trừ kho). Việc trừ kho thuộc về Kho hàng.
Đây có phải tính năng phiên ca POS không? Không - phiên POS (URD-POS) thuộc cùng dòng feature nhưng là một increment riêng; PRD này bao phủ phiếu bếp và các trạm.
References
- URD: Đơn hàng - Kitchen Tickets · Kitchen Stations · POS Sessions
- Xây trên: Sale Order
- Module: Đơn hàng - URD
- Developer: @nx/sale · @nx/core · domain model