PRD: Combos & bundles

Module	Products	PRD ID	PRD-BND-001
Status	Ready to dev	FEAT	BND
Epic	—	Plane	BANA-1551
Date	2026-06-15	Version	v1.0
Packages	@nx/core · @nx/commerce · @nx/sale	URD	BND
Surface	Client · Owner/MgrSale · POS
Owner	Phát Nguyễn

What combos & bundles are

The catalogue can already describe and price a single sellable variant (VAR, FAR), but it cannot yet describe a relationship between two variants - "this meal is a burger, fries, and a drink", "throw in a free sauce", "people who buy this also buy that". Merchants sell these every day. A POS that only rings up flat variants forces staff to key each part by hand and guess the price.

A combo is more than a label. The kitchen must see every physical part to make it, inventory must deduct each part's stock, and the bill must show one price - not the sum of the parts. Without a first-class bundle, a "combo" is either one un-decomposable line (kitchen and stock go blind) or a pile of separately-priced lines staff discount to zero by hand.

This PRD makes the bundle relationship first-class: the owner declares combo / add-on / FBT relationships on a variant, and at the point of sale the system expands a combo into a priced lead plus zero-priced parts, attaches add-ons and FBT items on demand, and refuses misconfigured graphs.

Three bundle types

A bundle always has a direction: from a lead variant to a related variant. The bundle type decides how the related side is priced and when it attaches to the cart.

Type	Price of the related side	When it attaches
Combo	Zero - the combo itself carries the price	The system expands it automatically the moment the lead (combo-typed) variant hits the cart
Add-on	Always free	Staff attach it manually at the point of sale, onto an existing lead line
Frequently-bought-together (FBT)	Its own price, or an override	Staff attach it at the point of sale as an up-sell suggestion

One combo, from cart to kitchen

An owner builds a "Lunch Combo" variant at one price and declares its components: 1 burger, 1 fries, 1 drink. A cashier adds the combo to the cart.

Step	What happens
1	The system loads the whole combo graph, checking depth and cycles
2	Creates one lead line carrying the combo's price
3	Creates three zero-priced component lines (burger, fries, drink), linked back to the lead
4	Reserves stock for each component

Ordering two combos doubles every component line automatically. The cashier attaches a paid extra sauce (FBT) to the combo lead and a free napkin set (add-on) to the burger line - both attach to an existing top-level lead line; neither attaches to the combo any other way.

Where this is easy to get wrong

Combo component lines are not directly editable

An owner or cashier never edits a component line inside a combo by hand - every change goes through the lead line, and the children scale automatically to the new combo quantity.

A combo also never expands forever: expansion has a fixed depth ceiling (5 levels), a cycle guard, and refuses empty combos. A misconfigured graph can never hang the cart or leave a combo with nothing for the kitchen to make.

1. Goals & Non-Goals

Goals

• Relate two variants with a typed bundle - combo, add-on, or frequently-bought-together - from a lead variant to a related variant.
• A combo carries its own price; its components expand into zero-priced child lines at cart-add.
• Scale each component by the combo quantity, and merge a component reached on multiple branches into one line.
• Support nested combos with a hard depth ceiling, refusing depth-exceeded, cyclic, or empty combos with a specific reason.
• Attach an add-on (always free) or an FBT item (its own or overridden price) to an existing top-level lead line at the point of sale.
• Build the whole bundle graph atomically with the variant, and record which combo and bundle produced each line for downstream use.

Non-Goals

• Pricing the combo itself - the combo lead is priced through its fare (FAR); this PRD only zeroes the components.
• Stock figures and reservation mechanics - expansion triggers reservation, but the stock model lives in Inventory.
• Bill-of-materials / manufacturing recipes - a separate concern in Inventory.
• Promotion-driven discounts on a bundle - discount calculation (CMP) is a separate, in-progress feature.
• Cartesian generation of combos from option axes - combos are declared, not generated (OPT).

2. Success Metrics

Metric	Target / signal
Combo decomposition	Every combo on an order yields one priced lead plus its full set of zero-priced components
Price integrity	A combo's bill amount equals its own fare, never the sum of its components
Expansion safety	No order is created from a combo that exceeds the depth limit, forms a cycle, or has no components
Quantity accuracy	A component's line quantity equals per-combo quantity × combo quantity, summed across branches
Attach correctness	An add-on / FBT item attaches only to a matching top-level lead line; a combo never attaches this way

3. Personas & Use Cases

Persona	Goal in this feature
Owner / Manager	Declare a combo's components, attachable add-ons, and FBT suggestions on the catalogue
Cashier	Ring up a combo as one line, attach an add-on or accept a suggestion at the point of sale
Kitchen / Fulfilment	See every physical component of a combo to prepare it

Core scenario: an owner builds a "Lunch Combo" variant at one price and declares its components - 1 burger, 1 fries, 1 drink. A cashier adds the combo; the system creates one priced lead line plus three zero-priced component lines beneath it. The cashier attaches a paid extra sauce (FBT) to the combo lead and a free napkin set (add-on) to the burger line. Ordering two combos doubles every component line automatically.

4. User Stories

#	As a	I want	So that
01	owner	declare a combo's components and quantities	kitchen and stock see the real parts while the guest sees one price
02	owner	offer a free add-on on a variant	staff attach it at the point of sale without re-pricing
03	owner	suggest a frequently-bought-together item with its own price	up-selling is one tap
04	cashier	add a combo as a single line and let the system fill in the components	I never key parts by hand
05	cashier	bump a combo's quantity and watch every component scale	the order stays correct
06	kitchen staff	see each component of a combo	I make exactly what was sold

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	A bundle relates a lead variant to a related variant with one of three types: combo, add-on, FBT.	✅	URD-BND-001
FR-002	A combo is composed of component variants, each with its own quantity. • The combo itself is priced. • Component prices are zero.	✅	URD-BND-002
FR-003	An add-on relates an always-free related variant to a host variant.	✅	URD-BND-003
FR-004	An FBT entry suggests a related variant, is directional, and may carry its own price override or fall back to the suggested variant's fare. • The override basis offers fixed / percentage / per-unit / tiered. • At the point of sale only fixed, per-unit, and percentage are applied (fixed and per-unit both set the unit price to the basis amount). • A tiered basis is not yet supported and is refused.	🔶	URD-BND-004
FR-005	The same (type, lead, related) relationship cannot be duplicated.	✅	URD-BND-005
FR-006	Bundles of a lead and type carry a display order.	✅	URD-BND-006
FR-007	Bundles are created atomically with the variant. Any failure rolls the whole create back.	✅	URD-BND-007 · URD-VAR-003
FR-008	Adding a combo to the cart expands it on the system side into a priced lead line plus zero-priced component child lines linked to the lead.	✅	URD-BND-008
FR-009	Each component's quantity is its per-combo quantity × the combo quantity. A component reached on multiple branches is merged into one line with summed quantity.	✅	URD-BND-009
FR-010	Combos may nest. Expansion recurses up to a maximum depth of five levels.	✅	URD-BND-010
FR-011	A combo exceeding the depth limit, forming a cycle, or having no components is refused with a specific reason.	✅	URD-BND-011
FR-012	Combo component lines cannot be edited directly. The owner edits the combo lead and children scale automatically.	✅	URD-BND-012
FR-013	A combo product variant must declare at least one combo component at creation.	✅	URD-BND-013
FR-014	An add-on or FBT item attaches at the point of sale to an existing top-level lead line, validated against the configured relationship. A combo cannot be attached this way.	✅	URD-BND-014
FR-015	An add-on still reserves inventory for its component even though it is free.	✅	URD-BND-015
FR-016	Each combo lead and component line records which combo and bundle produced it for downstream kitchen / refund / audit.	✅	URD-BND-016

5.1 Acceptance Criteria

• Create a variant and declare a combo, add-on, or FBT bundle to another variant → the bundle saves with the right type, lead variant, and related variant.
• Create a combo with components and their own quantities → the combo carries its own price, and each component line is zero-priced once expanded.
• Declare an add-on on a host variant → attaching it at the point of sale always prices at zero.
• Declare an FBT entry with a fixed, per-unit, or percentage price override → at the point of sale the FBT line prices exactly per the chosen basis; declare a tiered basis and add it at the point of sale → refused.
• Declare two bundles with the same type, lead, and related variant → the second declaration is refused as a duplicate.
• Declare several bundles of the same type on one lead with different display orders → the bundle list shows in the declared order.
• Create a combo variant with component bundles where one bundle is invalid (e.g. a duplicate) → the whole variant create is rolled back, nothing is saved.
• Add a combo to the cart → the cart shows one priced lead line with zero-priced component lines beneath it.
• Add two of the same combo where one component is reached through two different branches → that component merges into one line, quantity summed across both branches times the combo quantity.
• Create a combo whose component is itself another combo (nested up to five levels), then add it to the cart → every physical leaf component at every level expands fully.
• Create a combo nested beyond five levels, or a chain that loops back on itself, or a combo with no components, then add it to the cart → refused with a specific reason (depth exceeded / cycle / no components).
• Add a combo to an order, then try to edit a component line directly → blocked; edit the combo lead's quantity instead → every component line scales automatically.
• Create a combo-typed variant without declaring any component → refused at creation.
• Attach an add-on or FBT item to the exact top-level lead line its configured relationship points to → succeeds; try attaching it to a different lead line, or attaching a combo as an add-on → refused.
• Attach a free add-on to a line → the add-on's component still has stock reserved even though the line prices at zero.
• View a combo lead or component line on an order → the line carries the combo and the bundle that produced it.

6. Non-Functional Requirements

Area	Requirement
System-authoritative	Combo expansion and the bundle's type / price are decided by the system from the stored relationship, never trusted from the device
Atomicity	A combo's lead and every component line are written together; a stock-guard failure rolls back before any line is changed
Bounded expansion	The system loads the whole combo graph up front and flattens it step by step, capping at a fixed maximum depth, with explicit cycle and empty-combo guards - a misconfigured graph can never loop forever
Precision	Component quantities are multiplied and summed at 4-decimal precision
Tenancy & access	All operations confined to the user's own merchant and gated by product / sale permissions
Auditability	Every combo and component line carries the combo lead and the bundle that produced it
Languages	Combo and component names are carried bilingual (English and Vietnamese) in each line's snapshot

7. UX & Flows

On the catalogue, the owner declares a variant's combo components (with quantities), its attachable add-ons, and its FBT suggestions (with an optional price override). At the point of sale a combo shows as a single priced line with its components nested beneath; staff attach an add-on or accept an FBT suggestion against a lead line.

8. Data & Domain

Concept	Role in bundling
Bundle	One typed relationship (combo / add-on / FBT) from a lead variant to a related variant, carrying quantity, an optional price-override basis, and a display order
Variant	A combo-typed variant is the lead of its component bundles; a plain variant is a physical component leaf
Order line	At cart-add a combo becomes a priced lead line plus zero-priced child lines linked back to the lead

Conceptual only - full detail and invariants live in the commerce domain model. Links are soft references; integrity is enforced when expanding and creating, not by database constraints.

9. Dependencies & Assumptions

Depends on

#	Feature	What it depends on
01	Variants & all-in-one create (VAR, URD-VAR-003)	bundles are created together with the variant in one operation.
02	Variant types (URD-VAR-006)	a variant's combo type is what makes expansion recurse into its bundle.
03	Fares & pricing (FAR)	the combo lead is priced through its own fare; components are zeroed.
04	Inventory (Inventory)	each expanded component reserves stock at cart-add.
05	Orders	the ordering flow that expands a combo and attaches add-ons / FBT at the point of sale.

Assumptions

#	Assumption	If wrong
01	A combo variant always declares at least one component; a plain (non-combo) variant referenced by a combo is a physical leaf.	A combo with no component reaching the cart would bill the guest for a line the kitchen has nothing to make; blocked by FR-013 (a component must be declared at creation) and the empty-combo guard at expansion (FR-011).
02	The owner keeps the bundle graph acyclic and shallow; the depth, cycle, and empty-combo guards are safety nets, not the design intent.	A misconfigured combo that references itself or nests too deep would make expansion loop forever without a fixed depth ceiling and cycle detection (FR-010, FR-011).

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P2 - BND in the URD feature catalog, alongside VAR
Rollout	All merchants; no feature flag
Migration	None - bundles are created on the existing variant create path
Launch criteria	A combo adds as a priced lead plus zero-priced components; component quantities scale with the combo; depth-exceeded, cyclic, and empty combos are refused; add-ons / FBT attach only to a matching top-level lead; a combo cannot be attached as an add-on
Monitoring	Combo-expansion refusal rate by reason (depth, cycle, empty), attach-mismatch rate, combo-vs-component price consistency

References

• URD: Product - BND · VAR · FAR
• Sibling PRDs: Product catalogue, variants & identifiers · Product options & variant generation · Fare system & pricing
• Module: Product - URD
• Developer: @nx/commerce · @nx/core · Orders

Risks & Open Questions

#	Risk / question	Mitigation / status
01	A misconfigured combo references itself or nests too deep	A bounded pre-load + step-by-step flatten enforce a fixed maximum depth and detect cycles; the add is refused with a specific reason (FR-010, FR-011)
02	A combo with no components reaches the cart	Empty combos are refused at expansion; a combo variant must also declare a component at creation (FR-011, FR-013)
03	Device tampering with combo price or components	Expansion and the bundle type / price are decided by the system, derived from the stored relationship
04	Editing a combo component line directly desynchronizes the combo	Component lines are not directly editable; the owner edits the lead and components scale automatically (FR-012)
05	A free add-on silently oversells stock	An add-on reserves inventory for its component even though its price is zero (FR-015)

Frequently Asked Questions

#	Question	Answer
01	Why are a combo's components priced at zero?	The combo itself carries the price. The lead line holds the combo's fare; the components exist so the kitchen can make them and inventory can deduct them, not to be billed.
02	What happens when I add two of the same combo?	Every component line scales: a component's quantity is its per-combo amount times the combo quantity. The same component reached through more than one branch is merged into a single line, quantities summed.
03	Can a combo contain another combo?	Yes - combos may nest. Expansion recurses up to five levels; beyond that, or if the chain loops back on itself, the add is refused with a specific reason.
04	How do add-ons differ from FBT?	An add-on is always free and is attached to a host line. An FBT item is a directional suggestion that carries its own price - or an override - and is added when its trigger variant is bought. The override basis can be fixed, percentage, per-unit, or tiered, but at the point of sale only fixed, per-unit, and percentage are applied today; a tiered basis is not yet supported (it is refused).
05	Can I attach a combo to another line as an add-on?	No - a combo is expanded by the system as its own lead line and cannot be attached. Only add-on and FBT relationships attach to an existing top-level lead line.
06	Can I edit a combo's component line on the order?	No - components are not directly editable. Edit the combo lead instead and the components scale automatically.