From 07f199b69d526732dcc081ed223560d38d2cb9ca Mon Sep 17 00:00:00 2001 From: Ryan Moon Date: Mon, 30 Mar 2026 19:12:17 -0500 Subject: [PATCH] Add PIN unlock flow to POS frontend planning --- planning/28_Frontend_Strategy.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/planning/28_Frontend_Strategy.md b/planning/28_Frontend_Strategy.md index b79ef3a..163fea7 100644 --- a/planning/28_Frontend_Strategy.md +++ b/planning/28_Frontend_Strategy.md @@ -59,11 +59,29 @@ The platform uses a single backend API with multiple purpose-built frontends. Ea - Session management (clock in/out, cash drawer open/close, X/Z reports) - Offline resilience — queue transactions if network drops, sync when back +**PIN unlock:** + +The POS terminal stays authenticated but locks between use. Staff unlock with a 4-6 digit PIN instead of email/password. The PIN maps to their real user account — every action (sale, void, drawer open) is attributed to the person who unlocked. + +- Each user sets a numeric PIN from their profile or admin assigns one +- PIN is stored as a bcrypt hash on the user record (separate from password) +- POS lock screen shows a numeric keypad — tap PIN, unlock, start selling +- Auto-locks after configurable idle timeout (default: 2 minutes) +- Manual lock button always visible +- Shift change: current user walks away, screen locks, next user enters their PIN +- Wrong PIN: brief delay, max 5 attempts then require full login +- PIN unlock issues a short-lived JWT (or extends the existing session) scoped to POS permissions +- Backend: `POST /v1/auth/pin-login` — accepts `{ pin }`, returns token with same user identity and permissions +- PIN is optional — users without a PIN set must use full email/password login on the POS + +This gives full audit trail (who did what) without the friction of typing credentials hundreds of times a day. + **Key screens:** -1. **Sale screen** — product search (left), cart (right), totals + pay button (bottom) -2. **Payment screen** — amount due, payment method selection, card terminal status, change calculation -3. **Return/exchange screen** — lookup original transaction, select items, process refund -4. **Drawer management** — open session, cash drops, close session with counts +1. **Lock screen** — numeric keypad, current time, store name +2. **Sale screen** — product search (left), cart (right), totals + pay button (bottom) +3. **Payment screen** — amount due, payment method selection, card terminal status, change calculation +4. **Return/exchange screen** — lookup original transaction, select items, process refund +5. **Drawer management** — open session, cash drops, close session with counts **Hardware integration:** - Barcode scanner: keyboard wedge (types into focused input, no special API)