PRD: Product Picker
| Module | Sale (CORE-07) | PRD ID | PRD-PCK-001 |
| Status | Planned | Owner | Hải Cao · Khoa Nguyễn · Phát Nguyễn |
| Date | 2026-06-11 | Version | v0.1 (draft) |
| Packages | @nx/commerce · apps/sale-renderer | URD | PCK |
| Epic | BANA-1326 | Window | June 2026 (By Month) |
TL;DR
A cashier picks any sellable item in at most 3 taps. A Product's Options (size, ice, sugar…) resolve to exactly one ProductVariant with live pricing; single-variant items skip the chooser. Behind it: a variant-matrix API so the POS no longer guesses from a flat variant list.
1. Context & Problem
Today the POS lists pre-created variants flat - every size/colour is its own entry. There is no Options→Variant resolution step and no matrix API: picking the right variant of an option-heavy product is slow and error-prone, and the add-on/bundle modal covers only part of the job. Selecting one item is the single most repeated action at the counter - every extra tap is paid thousands of times a day.
2. Goals & Non-Goals
Goals - ≤3 taps to any item (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 and less ice, and the right variant with the right price is in the cart - 3 taps.
- 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.
- Tap product → option sheet (defaults pre-picked) → confirm → cart.
- Single-variant product → straight to cart.
- Barcode scan → straight to cart (no picker).
9. Data & Domain
- New variant-matrix API in commerce: option combinations → variantId, price, availability per channel; invalid combinations excluded server-side.
- No schema change expected - variants and options already exist; the gap is the resolution API + UI.
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/add-ons stay; this fixes single-product variant resolution.
References
URD PCK · Phase 2 - By Month · Epic BANA-1326