Storefront POS is the Terminal-only cashier flow for walk-in sales, cart management, payment, printing, cash drawer, and optional customer display/second screen.
App Entry Points
| App | Target |
|---|
| Mobile | not available |
| POS Terminal | StorefrontPosStack |
Workflow Overview
StorefrontPosStack: POS navigation, cart, checkout, printing, and second-screen stateorders.ts / invoices.ts: order, invoice, payment, and retry behavior when POS creates accounting documentsproducts.ts: product list, stock, price, and step-price context
Permissions And Guards
| Topic | Behavior |
|---|
| Terminal menu key | storefrontPos |
| deptCode menu set | -2, 1, 2, 3, 4, 7, 29, 21, 8, 9, 12, 20, 22, 23, 27, 28 |
| Branch rule | Terminal-only screen; customer-display/native Android changes live under apps/pos-terminal/android |
Main Workflow
- This menu exists only in POS Terminal, not Mobile.
- Second-screen/customer-display work must follow the project AGENTS instruction: verify, commit/push, then run
yarn terminal:android:8082.
- Cart totals must remain consistent with payment and printed documents.
- Do not mix this fulfillment-independent POS flow with Storefront Picking.
Mobile vs POS Terminal
| Topic | Mobile | POS Terminal |
|---|
| Screen shape | not available | StorefrontPosStack |
| List behavior | dedicated stack/list screen | split-pane list card in HomeScreen |
| Detail behavior | full-screen detail | right-side detail panel |
Business-rule parity
StorefrontPosStack has a terminal-specific cashier UI, not a separate sales domain. Its business behavior must stay aligned with Mobile sales orders and the Terminal order-detail form.
- UI/UX may differ for the larger screen, keyboard, split panes, and customer display.
- Item selection, step price, weight calculation, duplicate-item handling, booked-price restrictions (
currentStepPrice), stock checks, permissions, payload fields, and API error messages must remain equivalent.
- Order-level
bookingPriceId is not an item lock; follow Mobile and use it only for booking-source fallback data.
- Reuse stable shared helpers such as
src/utils/orderPayload.ts instead of maintaining separate payload rules.
Developer Handoff Map
| Area | Code |
|---|
| POS stack | apps/pos-terminal/src/screens/StorefrontPosStack |
| Native Android display | apps/pos-terminal/android |
| Shared order/payment services | apps/pos-terminal/src/services/orders.ts |
| Storefront fulfillment | HomeScreen/StorefrontDetailForm.tsx |