PRD: Product Picker

Module	Sale	PRD ID	PRD-PCK-001
Status	Ready to dev	FEAT	PCK · BANA-1420
Epic	BANA-1326	Plane	BANA-1558
Date	2026-06-11	Version	v0.1
Packages	@nx/sale · @nx/commerce	URD	PCK
Surface	Sale · POS
Owner	Hải Cao · Khoa Nguyễn · Phát Nguyễn

TL;DR

≤3 taps to pick a typical item and add it to cart. Options (size, ice, sugar…) resolve to exactly one variant with live pricing; single-variant items skip the picker entirely.

1. Context & Problem

Today the POS lists variants flat - every size or colour is its own entry. Picking the right variant of an option-heavy product is slow and error-prone, and the add-on modal covers only part of the job. Item selection is the most repeated action at the counter - every extra tap multiplies across thousands of transactions a day.

Build status: Backend option-value→variant resolution and a POS option picker already exist - selected values resolve to matching variants, invalid combinations return empty, and barcode lookup goes straight to a variant. Remaining gaps vs this spec: resolving to exactly one variant (not a filtered list), per-channel availability, a channel-resolved live price at resolution time, and a proactive option matrix that greys out dead-end values.

2. Goals & Non-Goals

Goals - ≤3 taps for typical items (URD-PCK-001) · options resolve to exactly one variant (002) · 1-variant items skip the chooser (003) · live price (004) · invalid combos unselectable (005) · sensible defaults (006) · barcode scan bypasses the picker (007).

Non-Goals - catalog data cleanup tooling (separate concern) · retail counter mode (PRD-RTL-001) · bundle/combo redesign.

3. Success Metrics

Metric	Target
Taps per option-product	≤3 (measured on real menus)
Mis-picks reported by pilot staff	Near zero

4. Personas & Use Cases

Cashier/waiter under peak load: needs the right variant fast, without reading a long flat list.

5. User Stories

• As a cashier, I tap a milk-tea, pick size L, confirm, and the right variant with the right price is in the cart - 3 taps. (Changing a second option, e.g. less ice, is a 4th tap.)
• As a cashier, I tap a bottled water and it's in the cart instantly.

6. Functional Requirements

Delivers URD PCK URD-PCK-001…007 (Musts 001-004; Shoulds 005-007).

7. Non-Functional Requirements

• Picker opens and resolves instantly on current POS hardware; no regression in search/scan speed.

8. UX & Flows

Design first: option chips (size/ice/sugar) with defaults pre-selected, price updating live, photo + name persistent. One confirm tap adds to cart.

1. Tap product → option sheet (defaults pre-picked) → confirm → cart.
2. Single-variant product → straight to cart.
3. Barcode scan → straight to cart (no picker).

Tap budget: product + each option changed from default + confirm. Single-variant = 1 · defaults accepted = 2 · one option changed = 3. Products needing 2+ non-default options exceed 3 - the ≤3 target is for typical items (§3 metric), not a hard cap for every product.

9. Data & Domain

• Option-to-variant resolution already exists in part: selected values filter to matching variants, invalid combinations return empty. The remaining gap is collapsing that to exactly one variant, adding channel-resolved price and per-channel availability, and refining the picker UX. No data model change expected.

10. Dependencies & Assumptions

Dependency	Why
Clean options/variants data entry (client forms)	Picker quality depends on catalog data quality
Design (June)	Blocks build

11. Risks & Open Questions

• Menus with messy legacy variants may resolve poorly → need a data audit on pilot merchants.
• Max option dimensions supported in v1 (proposal: 3).

12. Release Plan & Launch Criteria

Build June (WK24-26) · ship behind the existing sale screen. Launch: AC-PCK-01 passes on a live merchant menu; no slowdown vs today.

13. FAQ

• Does this replace the bundle modal? No - bundles and add-ons stay; this fixes variant resolution for single products.

References

URD PCK · Phase 2 - By Month · Epic BANA-1326