PRD: Combo & gói bán kèm

Module	Sản phẩm	PRD ID	PRD-BND-001
Trạng thái	Sẵn sàng dev	FEAT	BND
Epic	—	Plane	BANA-1551
Ngày	2026-06-15	Phiên bản	v1.0
Gói	@nx/core · @nx/commerce · @nx/sale	URD	BND
Surface	Client · Chủ/QLSale · POS
Phụ trách	Phát Nguyễn

Combo & gói bán kèm là gì

Danh mục đã mô tả và định giá được một biến thể (Variant) bán đơn lẻ (VAR, FAR), nhưng chưa diễn tả được quan hệ giữa hai biến thể - "bữa này gồm burger, khoai và nước", "tặng kèm một hũ sốt", "ai mua món này thường mua thêm món kia". Merchant bán những thứ đó hằng ngày. Một POS chỉ tính được biến thể phẳng buộc nhân viên gõ tay từng phần và đoán giá.

Combo không đơn thuần là một cái nhãn. Bếp phải thấy đủ từng phần vật lý để làm, kho phải trừ tồn từng phần, và hóa đơn phải hiện đúng một giá - không phải tổng các phần cộng lại. Thiếu một gói (Bundle) hạng-nhất, "combo" hoặc thành một dòng không tách được (bếp lẫn kho đều mù về thành phần), hoặc thành một mớ dòng định giá riêng mà nhân viên phải tự tay chiết khấu về không.

Bản PRD này nâng quan hệ gói lên hạng-nhất: chủ khai báo các quan hệ combo / add-on / FBT trên một biến thể; tại quầy, hệ thống tự bung combo thành một dòng dẫn có giá cùng các thành phần giá-không, gắn add-on và FBT khi cần, và từ chối những đồ thị cấu hình sai.

Ba kiểu gói

Một gói luôn có hướng: từ một biến thể dẫn tới một biến thể liên quan. Kiểu gói quyết định thành phần định giá ra sao và gắn vào giỏ lúc nào.

Kiểu	Giá của phần liên quan	Gắn vào giỏ lúc nào
Combo	Về không - combo mang giá riêng	Hệ thống tự bung ngay khi thêm biến thể dẫn (kiểu combo) vào giỏ
Add-on	Luôn miễn phí	Nhân viên tự gắn tại quầy vào một dòng dẫn có sẵn
Mua-kèm-thường-xuyên (FBT)	Giá riêng, hoặc một mức ghi-đè	Nhân viên gắn tại quầy như một gợi ý bán-thêm

Một combo, từ giỏ hàng tới bếp

Chủ dựng biến thể "Combo Trưa" với một mức giá và khai báo thành phần: 1 burger, 1 khoai, 1 nước. Thu ngân thêm combo vào giỏ.

Bước	Việc xảy ra
1	Hệ thống nạp toàn bộ đồ thị combo, kiểm độ sâu và chu trình
2	Tạo một dòng dẫn mang giá của combo
3	Tạo ba dòng thành phần giá-không (burger, khoai, nước), liên kết ngược về dòng dẫn
4	Giữ chỗ tồn cho từng thành phần

Đặt hai combo thì mọi dòng thành phần tự gấp đôi. Thu ngân gắn thêm một hũ sốt tính phí (FBT) vào dòng dẫn combo, và một bộ khăn miễn phí (add-on) vào dòng burger - cả hai đều gắn vào một dòng dẫn cấp-cao nhất có sẵn, không gắn được vào chính combo theo cách khác.

Chỗ dễ sai nhất

Dòng thành phần combo không sửa trực tiếp được

Chủ hoặc thu ngân không sửa tay một dòng thành phần bên trong combo - mọi sửa đổi đi qua dòng dẫn, và các dòng con tự nhân theo số lượng combo mới.

Combo cũng không tự bung vô hạn: việc bung có trần độ sâu cố định (5 cấp), có rào chu trình, và từ chối combo rỗng. Cấu hình sai không thể khiến giỏ hàng treo hay chứa một combo không có gì để bếp làm.

1. Mục tiêu & Loại trừ

Mục tiêu

• Liên kết hai biến thể bằng một gói có kiểu - combo, add-on hoặc mua-kèm-thường-xuyên - từ biến thể dẫn tới biến thể liên quan.
• Combo mang giá riêng; thành phần bung ra thành các dòng con giá-không khi thêm vào giỏ.
• Nhân mỗi thành phần theo số lượng combo, và gộp một thành phần đến từ nhiều nhánh về một dòng.
• Cho phép combo lồng nhau với trần độ sâu cứng, từ chối combo vượt độ sâu, có chu trình hoặc rỗng kèm lý do cụ thể.
• Gắn một add-on (luôn miễn phí) hoặc một mục FBT (giá riêng hoặc giá ghi-đè) vào một dòng dẫn cấp-cao nhất sẵn có tại quầy.
• Dựng toàn bộ đồ thị gói liền mạch cùng biến thể, và ghi lại combo cùng gói nào đã sinh ra mỗi dòng để dùng về sau.

Loại trừ

• Định giá bản thân combo - dòng dẫn combo được định giá qua fare của nó (FAR); PRD này chỉ đưa thành phần về không.
• Số liệu tồn và cơ chế giữ chỗ - việc bung kích hoạt giữ chỗ, nhưng mô hình tồn nằm ở Kho.
• Định mức nguyên vật liệu / công thức sản xuất - là mối quan tâm riêng ở Kho.
• Chiết khấu khuyến mãi trên một gói - tính chiết khấu (CMP) là tính năng riêng, đang triển khai.
• Sinh combo theo tổ hợp Descartes từ các trục tùy chọn - combo được khai báo, không tự sinh (OPT).

2. Thước đo thành công

Chỉ số	Mục tiêu / tín hiệu
Phân rã combo	Mỗi combo trên một đơn sinh ra một dòng dẫn có giá cùng đủ bộ thành phần giá-không
Toàn vẹn giá	Số tiền hóa đơn của combo bằng fare riêng của nó, không bao giờ là tổng các thành phần
An toàn bung	Không đơn nào được tạo từ một combo vượt độ sâu, có chu trình, hoặc không có thành phần
Chính xác số lượng	Số lượng dòng của một thành phần bằng số-lượng-mỗi-combo × số lượng combo, cộng dồn qua các nhánh
Gắn đúng	Một add-on / FBT chỉ gắn vào một dòng dẫn cấp-cao nhất khớp; combo không bao giờ gắn theo cách này

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Chủ / Quản lý	Khai báo thành phần combo, add-on có thể gắn, và gợi ý FBT trên danh mục
Thu ngân	Tính một combo như một dòng, gắn add-on hoặc chấp nhận gợi ý tại quầy
Bếp / Hoàn tất	Thấy mọi thành phần vật lý của một combo để chuẩn bị

Tình huống cốt lõi: chủ dựng biến thể "Combo Trưa" với một mức giá và khai báo thành phần - 1 burger, 1 khoai, 1 nước. Thu ngân thêm combo; hệ thống tạo một dòng dẫn có giá cùng ba dòng thành phần giá-không bên dưới. Thu ngân gắn một hũ sốt tính phí (FBT) vào dòng dẫn combo và một bộ khăn miễn phí (add-on) vào dòng burger. Đặt hai combo thì mọi dòng thành phần tự gấp đôi.

4. User Stories

#	Là một	Tôi muốn	Để
01	chủ	khai báo thành phần combo kèm số lượng	bếp và kho thấy phần thật còn khách chỉ thấy một giá
02	chủ	tặng một add-on miễn phí trên một biến thể	nhân viên gắn ngay tại quầy mà không phải định lại giá
03	chủ	gợi ý một món mua-kèm-thường-xuyên kèm giá riêng	bán-thêm chỉ trong một chạm
04	thu ngân	thêm một combo như một dòng và để hệ thống tự điền thành phần	khỏi gõ tay từng phần
05	thu ngân	tăng số lượng combo và thấy mọi thành phần nhân theo	đơn luôn đúng
06	nhân viên bếp	thấy từng thành phần của combo	làm đúng món đã bán

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Một gói liên kết một biến thể dẫn với một biến thể liên quan theo một trong ba kiểu: combo, add-on, FBT.	✅	URD-BND-001
FR-002	Combo cấu thành từ các biến thể thành phần, mỗi thành phần mang số lượng riêng. • Combo được định giá cho chính nó. • Giá của các thành phần bằng không.	✅	URD-BND-002
FR-003	Một add-on liên kết một biến thể liên quan luôn-miễn-phí với một biến thể chủ.	✅	URD-BND-003
FR-004	Một mục FBT gợi ý một biến thể liên quan, có hướng và có thể mang giá ghi-đè riêng hoặc lùi về fare của biến thể được gợi ý. • Cơ sở ghi-đè cho phép cố định / phần trăm / theo-đơn-vị / bậc thang. • Tại điểm bán chỉ áp dụng cố định, theo-đơn-vị và phần trăm (cố định và theo-đơn-vị đều đặt đơn giá bằng giá trị cơ sở). • Bậc thang chưa được hỗ trợ và bị từ chối.	🔶	URD-BND-004
FR-005	Cùng một quan hệ (kiểu, dẫn, liên quan) không thể trùng lặp.	✅	URD-BND-005
FR-006	Các gói của một biến thể dẫn và một kiểu mang thứ tự hiển thị.	✅	URD-BND-006
FR-007	Các gói được tạo liền mạch cùng biến thể. Mọi lỗi khiến toàn bộ thao tác tạo bị quay lui.	✅	URD-BND-007 · URD-VAR-003
FR-008	Thêm một combo vào giỏ bung nó ở phía hệ thống thành một dòng dẫn có giá cùng các dòng con thành phần giá-không liên kết với dòng dẫn.	✅	URD-BND-008
FR-009	Số lượng mỗi thành phần là số-lượng-mỗi-combo × số lượng combo. Một thành phần đến từ nhiều nhánh được gộp vào một dòng với số lượng cộng dồn.	✅	URD-BND-009
FR-010	Combo có thể lồng nhau. Việc bung đệ quy đến tối đa năm cấp độ sâu.	✅	URD-BND-010
FR-011	Một combo vượt giới hạn độ sâu, tạo chu trình, hoặc không có thành phần bị từ chối kèm lý do cụ thể.	✅	URD-BND-011
FR-012	Dòng thành phần combo không thể sửa trực tiếp. Chủ sửa dòng dẫn combo và các con tự nhân theo.	✅	URD-BND-012
FR-013	Một biến thể sản phẩm combo phải khai báo ít nhất một thành phần combo khi tạo.	✅	URD-BND-013
FR-014	Một mục add-on hoặc FBT gắn tại điểm bán vào một dòng dẫn cấp-cao nhất hiện có, được kiểm khớp với quan hệ đã cấu hình. Combo không thể gắn theo cách này.	✅	URD-BND-014
FR-015	Một add-on vẫn giữ chỗ tồn cho thành phần của nó dù miễn phí.	✅	URD-BND-015
FR-016	Mỗi dòng dẫn combo và dòng thành phần ghi lại combo cùng gói đã sinh ra nó cho bếp / hoàn tiền / kiểm toán về sau.	✅	URD-BND-016

5.1 Tiêu chí nghiệm thu

• Tạo một biến thể và khai báo một gói kiểu combo, add-on hoặc FBT tới một biến thể khác → gói lưu đúng kiểu, đúng biến thể dẫn và biến thể liên quan.
• Tạo một combo với các thành phần kèm số lượng riêng → combo mang giá của chính nó, mỗi dòng thành phần khi bung ra mang giá bằng không.
• Khai báo một add-on trên một biến thể chủ → gắn add-on đó tại quầy luôn tính giá bằng không.
• Khai báo một mục FBT với giá ghi-đè cố định, theo-đơn-vị hoặc phần trăm → tại quầy, đơn giá mục FBT tính đúng theo cơ sở đã chọn; khai báo cơ sở bậc thang rồi thêm tại quầy → bị từ chối.
• Khai báo hai gói cùng kiểu, cùng biến thể dẫn, cùng biến thể liên quan → lần khai báo thứ hai bị từ chối vì trùng lặp.
• Khai báo nhiều gói cùng kiểu trên một biến thể dẫn kèm thứ tự hiển thị khác nhau → danh sách gói hiển thị đúng thứ tự đã khai.
• Tạo một biến thể combo kèm các gói thành phần, một gói trong đó không hợp lệ (ví dụ trùng lặp) → toàn bộ thao tác tạo biến thể bị hủy, không có gói hay biến thể nào được lưu.
• Thêm một combo vào giỏ → giỏ hiện một dòng dẫn có giá cùng các dòng thành phần bên dưới, giá bằng không.
• Thêm hai combo cùng loại mà một thành phần xuất hiện ở hai nhánh khác nhau trong combo → dòng thành phần đó gộp lại thành một dòng, số lượng bằng tổng cả hai nhánh nhân với số lượng combo.
• Tạo một combo có một thành phần là một combo khác (lồng tối đa năm cấp) rồi thêm vào giỏ → mọi thành phần lá vật lý ở mọi cấp đều được bung ra đủ.
• Tạo một combo lồng vượt năm cấp, hoặc một chuỗi combo vòng lại chính nó, hoặc một combo không thành phần, rồi thêm vào giỏ → bị từ chối kèm lý do cụ thể (vượt độ sâu / có chu trình / không thành phần).
• Thêm một combo vào đơn rồi thử sửa trực tiếp một dòng thành phần → bị chặn; sửa số lượng dòng dẫn combo thay vào đó → mọi dòng thành phần tự nhân theo.
• Tạo một biến thể kiểu combo mà không khai báo thành phần nào → bị từ chối ngay khi tạo.
• Gắn một add-on hoặc mục FBT vào đúng dòng dẫn cấp-cao nhất mà quan hệ đã cấu hình trỏ tới → gắn thành công; thử gắn vào một dòng dẫn khác, hoặc gắn một combo như add-on → bị từ chối.
• Gắn một add-on miễn phí vào một dòng → tồn của thành phần add-on vẫn bị trừ giữ chỗ dù dòng đó tính giá bằng không.
• Xem một dòng combo hoặc dòng thành phần trên đơn → dòng đó mang thông tin combo và gói đã sinh ra nó.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Hệ thống quyết định	Việc bung combo và kiểu / giá của gói do hệ thống quyết từ quan hệ đã lưu, không bao giờ tin theo thiết bị
Liền mạch	Dòng dẫn của một combo và mọi dòng thành phần được ghi cùng nhau; một lỗi rào tồn quay lui trước khi đổi bất kỳ dòng nào
Bung có giới hạn	Hệ thống nạp toàn bộ đồ thị combo lên trước rồi làm phẳng từng bước, chặn ở độ sâu tối đa cố định, kèm rào chu trình và combo rỗng tường minh - một đồ thị sai không bao giờ lặp vô hạn
Độ chính xác	Số lượng thành phần được nhân và cộng ở độ chính xác 4 chữ số thập phân
Đa thuê & truy cập	Mọi thao tác giới hạn trong merchant của người dùng và chặn bởi quyền sản phẩm / bán
Khả năng kiểm toán	Mọi dòng combo và thành phần mang dòng dẫn combo cùng gói đã sinh ra nó
Ngôn ngữ	Tên combo và thành phần được mang song ngữ (tiếng Anh và tiếng Việt) trong snapshot mỗi dòng

7. UX & Luồng

Trên danh mục, chủ khai báo cho một biến thể: các thành phần combo (kèm số lượng), các add-on có thể gắn, và các gợi ý FBT (kèm giá ghi-đè tùy chọn). Tại quầy, combo hiện thành một dòng có giá với thành phần lồng bên dưới; nhân viên gắn một add-on hoặc chấp nhận một gợi ý FBT vào một dòng dẫn.

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò trong gói
Gói (Bundle)	Một quan hệ có kiểu (combo / add-on / FBT) từ một biến thể dẫn tới một biến thể liên quan, mang số lượng, một cơ sở giá ghi-đè tùy chọn, và một thứ tự hiển thị
Biến thể (Variant)	Một biến thể kiểu combo là dẫn của các gói thành phần; một biến thể thường là một thành phần lá vật lý
Dòng đơn (Order line)	Khi thêm vào giỏ, một combo trở thành một dòng dẫn có giá cùng các dòng con giá-không liên kết ngược về dẫn

Chỉ ở mức khái niệm - chi tiết và bất biến đầy đủ nằm ở mô hình miền commerce. Liên kết là tham chiếu mềm; toàn vẹn được thực thi khi bung và khi tạo, không bởi ràng buộc CSDL.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	Biến thể & tạo trọn-gói (VAR, URD-VAR-003)	các gói được tạo cùng biến thể trong một thao tác.
02	Kiểu biến thể (URD-VAR-006)	kiểu combo của một biến thể là thứ khiến việc bung đệ quy vào gói của nó.
03	Fare & định giá (FAR)	dòng dẫn combo được định giá qua fare riêng; thành phần về không.
04	Kho (Kho)	mỗi thành phần được bung giữ chỗ tồn khi thêm vào giỏ.
05	Đơn hàng	luồng đặt đơn bung một combo và gắn add-on / FBT tại quầy.

Giả định

#	Giả định	Sai thì sao
01	Một biến thể combo luôn khai báo ít nhất một thành phần; một biến thể thường (không-combo) được một combo tham chiếu là một lá vật lý.	Một combo không thành phần lọt tới giỏ hàng thì khách trả tiền cho một dòng mà bếp không nhận được gì để làm; chặn bằng FR-013 (bắt buộc khai thành phần khi tạo) và rào combo-rỗng lúc bung (FR-011).
02	Chủ giữ đồ thị gói không-chu-trình và nông; rào chắn độ sâu, chu trình và combo rỗng là lưới an toàn, không phải chủ ý thiết kế.	Một combo cấu hình sai tham chiếu vòng lại chính nó hoặc lồng quá sâu sẽ khiến việc bung chạy vô hạn nếu không có trần độ sâu cố định và phát hiện chu trình (FR-010, FR-011).

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P2 - BND trong danh mục feature URD, cạnh VAR
Rollout	Toàn bộ merchant; không feature flag
Migration	Không - các gói được tạo trên đường tạo biến thể hiện có
Tiêu chí phát hành	Một combo thêm vào như dòng dẫn có giá cùng thành phần giá-không; số lượng thành phần nhân theo combo; combo vượt độ sâu, có chu trình và rỗng bị từ chối; add-on / FBT chỉ gắn vào một dòng dẫn cấp-cao nhất khớp; một combo không thể gắn như add-on
Theo dõi	Tỷ lệ từ chối bung combo theo lý do (độ sâu, chu trình, rỗng), tỷ lệ gắn-lệch, nhất quán giá combo-vs-thành phần

Tham chiếu

• URD: Sản phẩm - BND · VAR · FAR
• PRD liên quan: Danh mục sản phẩm, biến thể & định danh · Tùy chọn sản phẩm & sinh biến thể · Hệ thống fare & định giá
• Module: Sản phẩm - URD
• Developer: @nx/commerce · @nx/core · Đơn hàng

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Một combo cấu hình sai tham chiếu chính nó hoặc lồng quá sâu	Nạp-trước có giới hạn + làm-phẳng từng bước thực thi độ sâu tối đa cố định và phát hiện chu trình; việc thêm bị từ chối kèm lý do cụ thể (FR-010, FR-011)
02	Một combo không có thành phần lọt tới giỏ	Combo rỗng bị từ chối khi bung; một biến thể combo cũng phải khai báo một thành phần khi tạo (FR-011, FR-013)
03	Thiết bị can thiệp giá hoặc thành phần combo	Việc bung và kiểu / giá gói do hệ thống quyết, suy ra từ quan hệ đã lưu
04	Sửa trực tiếp dòng thành phần combo làm lệch combo	Dòng thành phần không sửa trực tiếp được; chủ sửa dòng dẫn và thành phần tự nhân theo (FR-012)
05	Một add-on miễn phí âm thầm bán quá tồn	Một add-on giữ chỗ tồn cho thành phần dù giá bằng không (FR-015)

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Vì sao thành phần combo định giá bằng không?	Vì bản thân combo đã mang giá. Dòng dẫn giữ fare của combo; thành phần ở đó để bếp làm và kho trừ tồn, không phải để tính tiền.
02	Thêm hai combo giống nhau thì sao?	Mọi dòng thành phần nhân theo: số lượng một thành phần bằng lượng-mỗi-combo nhân số lượng combo. Cùng một thành phần đến qua nhiều nhánh được gộp vào một dòng, số lượng cộng dồn.
03	Một combo có chứa combo khác được không?	Được - combo có thể lồng nhau. Việc bung đệ quy đến năm cấp; vượt mức đó, hoặc nếu chuỗi vòng lại chính nó, việc thêm bị từ chối kèm lý do cụ thể.
04	Add-on khác FBT chỗ nào?	Add-on luôn miễn phí và gắn vào một dòng chủ. Mục mua-kèm-thường-xuyên là một gợi ý có hướng, mang giá riêng - hoặc một giá ghi-đè - và được thêm khi mua biến thể kích hoạt nó. Cơ sở ghi-đè có thể là cố định, phần trăm, theo-đơn-vị hoặc bậc thang, nhưng tại điểm bán hiện chỉ áp dụng cố định, theo-đơn-vị và phần trăm; bậc thang chưa được hỗ trợ (bị từ chối).
05	Tôi có thể gắn một combo vào dòng khác như add-on không?	Không - combo được hệ thống bung thành dòng dẫn riêng và không thể gắn. Chỉ quan hệ add-on và FBT mới gắn vào một dòng dẫn cấp-cao nhất hiện có.
06	Tôi có thể sửa dòng thành phần của một combo trên đơn không?	Không - thành phần không sửa trực tiếp được. Hãy sửa dòng dẫn combo và thành phần tự nhân theo.