489 lines
31 KiB
Markdown
489 lines
31 KiB
Markdown
# POS Architecture — Mercado de Vida
|
||
|
||
> **Status:** Discovery (Phase 1)
|
||
> **Ticket:** POS-001
|
||
> **Author:** architect
|
||
> **Last updated:** 2026-08-21
|
||
|
||
This document describes how a Point-of-Sale (TPV) application integrates into the existing **Mercado de Vida** modular monolith. The POS must reuse products, prices, stock, customers, orders, taxes, authentication, RBAC and the admin panel. **No business-logic duplication.**
|
||
|
||
---
|
||
|
||
## 0. Executive summary
|
||
|
||
| Aspect | Decision |
|
||
|---|---|
|
||
| Frontend app | New Next.js app `apps/pos` inside the existing `project/` workspace (sibling to `apps/admin`). Same Tailwind design tokens, same catch-all proxy pattern, same auth flow as the admin. |
|
||
| Backend | New module `project/src/modules/pos/` following the existing `domain / application / infrastructure / api` layout. Reuses all existing modules via injected ports. |
|
||
| Sales = orders | A POS sale IS an order with `source = 'pos'`. New column on `orders_orders`. The order state machine is extended with a `COMPLETED` terminal state (no shipping). |
|
||
| Cash sessions, terminals, stores | New tables. Schema below. |
|
||
| Inventory per store | Extended: `inventory_stock` becomes keyed by `(variant_id, store_id)`. Migration backfills the default store. |
|
||
| Authentication | Reuses the existing `backoffice_users` table (admin/editor + new `pos_cashier`, `pos_manager` roles). Same session cookie mechanism. |
|
||
| Hardware | Adapter interfaces (no vendor SDK in core). Browser-first implementations; real ESC/POS adapters land in Phase 7. |
|
||
| Idempotency | Reuses `idempotency_key` on orders. POS generates a UUID per "cobrar" click. |
|
||
|
||
The POS is **not** a parallel system. It is a new consumer of the same core modules, plus a thin new module for the TPV-specific concepts (terminals, sessions, registers).
|
||
|
||
---
|
||
|
||
## 1. Current stack (as-found)
|
||
|
||
### 1.1 Repository layout
|
||
|
||
```
|
||
project/
|
||
├── apps/
|
||
│ ├── admin/ # Next.js 14 admin (Backoffice users)
|
||
│ ├── frontend/ # Next.js 14 customer storefront
|
||
│ └── storefront/ # legacy customer storefront (being phased out)
|
||
├── src/
|
||
│ ├── app/ # Fastify composition root (build-app.ts)
|
||
│ ├── infrastructure/# server bootstrap, config, logger
|
||
│ ├── modules/ # 20+ domain modules (DDD + Clean Architecture)
|
||
│ └── shared/ # cross-module helpers (auth, errors, http-input, telemetry, text)
|
||
├── migrations/ # node-pg-migrate
|
||
├── scripts/ # dev helpers
|
||
├── docker-compose.yml # postgres + redis
|
||
└── package.json # ESM, TypeScript strict, vitest
|
||
```
|
||
|
||
Apps are co-located under `project/apps/` and share backend through a single Next.js catch-all proxy (`/api/[...path]/route.ts`). The `monolith.sh` script orchestrates all services on ports 3000 (backend), 3003 (frontend), 3004 (admin), 3005 (storefront).
|
||
|
||
### 1.2 Backend conventions
|
||
|
||
- **Module layout (mandatory):** `domain / application / infrastructure / api`. Public API exposed only via `index.ts`.
|
||
- **Module isolation:** modules import ONLY public APIs of other modules; the boundary checker (`scripts/check-module-boundaries.mjs`) enforces this.
|
||
- **Auth:** `Authenticate` port from `shared/auth.ts`; routes call `await deps.authenticate(request)` and then `requireRole(user, 'admin' | 'editor' | 'customer')`.
|
||
- **RBAC:** role-based string check in `requireRole`. Permissions are an enum in `apps/admin/src/lib/permissions.ts` (admin only, currently).
|
||
- **Validation:** explicit `parseJson(zodSchema, request.body)` via `shared/http-input.ts`. No magic.
|
||
- **Errors:** `AppError(httpStatus, code, message, details?)` from `shared/errors.ts`. Single envelope.
|
||
- **DB:** PostgreSQL 16, schema-per-module naming `<module>_<table>`. node-pg-migrate, ES module migrations.
|
||
- **Logging:** structured pino via `app.log`.
|
||
- **Telemetry:** `Telemetry` / `Tracer` / `Meter` ports from `observability` (no-op default).
|
||
- **Tests:** vitest unit + itest (integration) inside `src/modules/<m>/tests/`. E2E in `src/app/tests/e2e/`.
|
||
|
||
### 1.3 Existing modules we will reuse
|
||
|
||
| Module | What POS needs from it |
|
||
|---|---|
|
||
| `identity` | `Authenticate` port, backoffice session lookup (cookie + role). |
|
||
| `backoffice` | Login/logout/me endpoints and the cookie contract. Reused as-is. |
|
||
| `catalog` | Product / variant / image / category / brand lookups + search by EAN/SKU/name (`GET /products/search`, `GET /products/suggest`). |
|
||
| `pricing` | `GET /pricing/variants/:id`, `POST /pricing/calculate`. Server-authoritative price; never trust client totals. |
|
||
| `inventory` | `checkAvailability`, atomic `reserve / release / confirm`. The POS sale = `confirm` of a `reserve`. |
|
||
| `tax` | Active tax rates via `GET /admin/tax-rates`. |
|
||
| `orders` | Order creation, state transitions, idempotency. |
|
||
| `payments` | `PaymentProvider` interface — currently a stub. POS brings concrete `cash` and external `card` providers in Phase 3. |
|
||
| `checkout` | The orchestrator pattern (validate → price → reserve → create order → payment intent). POS re-uses the same flow but skips shipping. |
|
||
| `users` | Customer search by email/phone for ticket association. |
|
||
| `store-settings` | `store_name`, `contact_address`, `footer_text`, etc. — printed on tickets. |
|
||
| `security` | `AuditLogger` for "open register", "close register", "discount applied", etc. |
|
||
| `notifications` | Email on sale confirmation (optional, off by default for POS). |
|
||
| `observability` | `Tracer` / `Meter` for spans and counters. |
|
||
|
||
### 1.4 Existing admin app conventions (POS will mirror them)
|
||
|
||
- App Router under `apps/admin/src/app/(dashboard)/...`.
|
||
- Tailwind with shared `@theme` block (greens `#2D6A4F`, `#1B4332`; secondary cream `#F5F0E8`; accent orange `#E76F51`; danger `#DC2626`).
|
||
- `AuthProvider` context, `useAuth()` hook, `requireRole` redirect to `/login`.
|
||
- `lib/api-client.ts` with typed namespaces (`productsApi`, `brandsApi`, `ordersApi`, …). Catch-all proxy at `app/api/[...path]/route.ts`.
|
||
- Tanstack-Query-like manual caching via `useEffect` + `useState` (no Redux/Zustand yet).
|
||
- `lib/permissions.ts` for client-side UI gating.
|
||
|
||
---
|
||
|
||
## 2. Gaps to address before code
|
||
|
||
These are real schema/concept gaps the brief asks for that **do not exist today**:
|
||
|
||
| Gap | Brief section | Current state | Resolution |
|
||
|---|---|---|---|
|
||
| **Multi-store** | §17 | `inventory_stock` keyed by `variant_id` only. **No** `store` table. | Add `stores` table; key `inventory_stock` by `(variant_id, store_id)`. Migration backfills default store. |
|
||
| **Terminals** | §17 | None. | New `pos_terminals` table. |
|
||
| **Cash sessions** | §18 | None. | New `pos_cash_sessions` table. |
|
||
| **Order source** | §16 | No `source` column on `orders_orders`. | Add `source` enum (`'ecommerce' \| 'pos' \| 'admin'`) with default `'ecommerce'`. Backfill existing rows. |
|
||
| **Order `COMPLETED` state** | §16, §39 | State machine tops out at `DELIVERED`. POS sales never ship. | Add `COMPLETED` terminal state. POS sales go `PENDING → AWAITING_PAYMENT → PAID → COMPLETED` (skipping `SHIPPED`/`DELIVERED`). |
|
||
| **POS roles** | §27 | Roles are `customer / admin / editor`. | Extend `backoffice_users.role` CHECK to include `'pos_cashier'` and `'pos_manager'`. |
|
||
| **POS-only permissions** | §27 | Permissions enum is admin-only. | Extend `permissions.ts` with `POS_*` permissions; server-side `requireRole` is too coarse — add `requireAnyRole` and `requirePermission` to `shared/auth.ts`. |
|
||
| **Anonymous sale** | §14 | `orders_orders.user_id NOT NULL`. | Either create a "walk-in customer" placeholder or make `user_id` nullable when `source = 'pos'`. Decision: **nullable** with a CHECK that requires `user_id IS NULL OR source = 'pos'` if guest, otherwise required. |
|
||
| **Hardware adapters** | §25 | None. | New interfaces under `shared/hardware/`: `ScannerAdapter`, `PrinterAdapter`, `CashDrawerAdapter`, `PaymentTerminalAdapter`, `ScaleAdapter`. Browser implementation in Phase 2/3; ESC/POS in Phase 7. |
|
||
| **Idempotency per sale** | §32 | Already supported via `idempotency_key` UNIQUE. | Reused as-is. POS client generates a UUID per "Cobrar" click. |
|
||
|
||
---
|
||
|
||
## 3. Proposed architecture
|
||
|
||
### 3.1 High-level diagram
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ Mercado de Vida Core │
|
||
│ │
|
||
┌──────────┐ │ ┌─────────┐ ┌─────────┐ ┌────────────┐ │
|
||
│ Ecommerce│─────────┼─►│Catalog │ │Pricing │ │ Inventory │ │
|
||
│ Frontend │ API │ └────┬────┘ └────┬────┘ └─────┬──────┘ │
|
||
└──────────┘ │ │ │ │ │
|
||
│ └────────────┼──────────────┘ │
|
||
┌──────────┐ │ ▼ │
|
||
│ Admin │─────────┼─► ┌──────────────────────────────┐ │
|
||
│ Panel │ API │ │ Orders (source=ecommerce/pos/admin) │
|
||
└──────────┘ │ └──────────────────────────────┘ │
|
||
│ │ │
|
||
┌──────────┐ │ ▼ │
|
||
│ POS │─────────┼─► ┌──────────────────────────────┐ │
|
||
│ (new) │ API │ │ Payments (cash / card stub) │ │
|
||
│ apps/pos │ │ └──────────────────────────────┘ │
|
||
└────┬─────┘ │ │ │
|
||
│ hardware │ ▼ │
|
||
▼ adapters │ ┌──────────────┐ │
|
||
┌──────────┐ │ │ Audit Log │ │
|
||
│ Scanner │ │ └──────────────┘ │
|
||
│ Printer │ │ │
|
||
│ Cash drw │ └──────────────────────────────────────────────┘
|
||
│ Card Trm │
|
||
└──────────┘
|
||
```
|
||
|
||
### 3.2 Backend modules
|
||
|
||
```
|
||
src/modules/
|
||
├── pos/ # NEW — POS-specific concepts
|
||
│ ├── domain/
|
||
│ │ ├── store.ts # Store aggregate
|
||
│ │ ├── terminal.ts # POS terminal
|
||
│ │ ├── cash-session.ts # Open/closed register session
|
||
│ │ ├── quick-product.ts # Configurable favorite buttons
|
||
│ │ ├── sale.ts # Re-exports Order as Sale; defines Source enum
|
||
│ │ └── errors.ts
|
||
│ ├── application/
|
||
│ │ ├── open-cash-session.ts
|
||
│ │ ├── close-cash-session.ts
|
||
│ │ ├── list-terminals.ts
|
||
│ │ ├── get-pos-config.ts # returns terminal, session, store, tax rates
|
||
│ │ ├── search-products-for-pos.ts # thin wrapper over catalog search + price
|
||
│ │ ├── create-pos-sale.ts # orchestrates pricing + reserve + create + complete
|
||
│ │ ├── refund-pos-sale.ts
|
||
│ │ ├── park-ticket.ts # cart parked in DB
|
||
│ │ └── ...
|
||
│ ├── infrastructure/
|
||
│ │ ├── pg-store-repository.ts
|
||
│ │ ├── pg-terminal-repository.ts
|
||
│ │ ├── pg-cash-session-repository.ts
|
||
│ │ ├── pg-quick-product-repository.ts
|
||
│ │ └── pg-parked-ticket-repository.ts
|
||
│ └── api/
|
||
│ └── pos.routes.ts # all /pos/* endpoints
|
||
└── (existing modules, untouched except where noted)
|
||
```
|
||
|
||
### 3.3 POS order flow (orchestration)
|
||
|
||
The POS sale path is a **slimmer** checkout: no shipping, no promo code, optional customer. We re-use `OrderService` and `InventoryService` directly rather than building a separate orchestrator.
|
||
|
||
```
|
||
[POS UI: Cart with N items]
|
||
│
|
||
│ POST /api/pos/sales { idempotencyKey, items, customerId?, payments, discount? }
|
||
│
|
||
▼
|
||
pos.routes.ts
|
||
│
|
||
├─► requireRole(user, ['pos_cashier','pos_manager','admin'])
|
||
├─► requireOpenSession(terminalId) // 409 if closed
|
||
├─► for each item:
|
||
│ pricingApi.getVariantPrice(variantId) // server-authoritative
|
||
│ inventory.checkAvailability(variantId) // soft check (real check at confirm)
|
||
├─► compute totals server-side (no client trust)
|
||
├─► BEGIN TRANSACTION
|
||
│ ordersService.create({source:'pos', userId?, items, totals, idempotencyKey})
|
||
│ inventory.reserve(variantId, storeId, qty) × items
|
||
│ ordersService.transition(orderId, 'AWAITING_PAYMENT')
|
||
│ for each payment: paymentsService.registerCash/Card({orderId, amountCents, ...})
|
||
│ ordersService.transition(orderId, 'PAID')
|
||
│ for each payment: inventory.confirm(reservation) × items
|
||
│ ordersService.transition(orderId, 'COMPLETED')
|
||
│ auditLogger.log('pos.sale.completed', {orderId, terminalId, totalCents, ...})
|
||
│ COMMIT
|
||
│
|
||
▼
|
||
[POS UI: Receipt rendered, print dispatched, new empty cart]
|
||
```
|
||
|
||
Key invariants:
|
||
|
||
- **Idempotency:** the same `idempotencyKey` returns the same order — no double-charge on network retry.
|
||
- **Atomicity:** everything is in one PG transaction (using a single connection / client). The existing `OrderService` and `InventoryService` already operate on a passed `pg.Client`; we wire them to a single txn.
|
||
- **Server-authoritative totals:** client sends only item ids + quantities; server computes price, tax, discount.
|
||
- **No double reservation:** the orchestration is linear and single-threaded per request.
|
||
|
||
### 3.4 Hardware abstraction
|
||
|
||
```ts
|
||
// project/src/shared/hardware/types.ts
|
||
|
||
export interface ScannerAdapter {
|
||
/** Subscribe to decoded codes. Most physical scanners are HID-keyboard;
|
||
* we wrap them in this interface so swapping to serial/BT is a one-line change. */
|
||
onCode(callback: (code: string) => void): () => void;
|
||
}
|
||
|
||
export interface PrinterAdapter {
|
||
/** Renders a structured receipt. Returns success/failure; never throws
|
||
* for "printer offline" (returns a structured failure instead). */
|
||
print(receipt: ReceiptPayload): Promise<{ ok: true; jobId: string } | { ok: false; reason: string }>;
|
||
}
|
||
|
||
export interface CashDrawerAdapter {
|
||
/** Pulses the cash-drawer kick-out. Best-effort; failures logged. */
|
||
open(): Promise<{ ok: boolean; reason?: string }>;
|
||
}
|
||
|
||
export interface PaymentTerminalAdapter {
|
||
/** Asks the datáfono for an authorisation. Returns approved/declined/error.
|
||
* No PAN handling: this delegates to a PCI-DSS-compliant provider. */
|
||
requestPayment(input: { amountCents: number; currency: 'EUR'; reference: string }): Promise<
|
||
| { ok: true; providerPaymentId: string; authCode: string }
|
||
| { ok: false; reason: 'declined' | 'timeout' | 'offline' | 'error'; message: string }
|
||
>;
|
||
}
|
||
|
||
export interface ScaleAdapter {
|
||
/** Reads weight in grams. Returns null if the scale is disconnected or settling. */
|
||
readGrams(): Promise<number | null>;
|
||
}
|
||
```
|
||
|
||
Each adapter has two implementations in Phase 7:
|
||
|
||
- **Browser** (Phase 2/3): relies on standard browser APIs. Scanner = keyboard listener on a focused input. Printer = hidden iframe to a print-friendly HTML route. Cash drawer = no-op. Payment terminal = manual entry (operator types last-4 or auth code).
|
||
- **Native bridge** (Phase 7, deferred): a thin Node addon or a sidecar process that speaks USB/serial/ESC-POS. Exposed over a localhost HTTP socket to the Next.js app.
|
||
|
||
### 3.5 Frontend app
|
||
|
||
```
|
||
apps/pos/
|
||
├── package.json
|
||
├── next.config.ts
|
||
├── tailwind.config.ts (or shared via project root)
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ ├── layout.tsx
|
||
│ │ ├── globals.css
|
||
│ │ ├── (auth)/
|
||
│ │ │ └── login/page.tsx
|
||
│ │ ├── (terminal)/
|
||
│ │ │ ├── layout.tsx # minimal chrome — sidebar, connection status
|
||
│ │ │ ├── page.tsx # main register screen
|
||
│ │ │ ├── open-register/page.tsx
|
||
│ │ │ ├── close-register/page.tsx
|
||
│ │ │ ├── history/page.tsx
|
||
│ │ │ └── settings/page.tsx
|
||
│ │ └── api/
|
||
│ │ └── [...path]/route.ts # identical proxy to apps/admin
|
||
│ ├── components/
|
||
│ │ ├── pos/POSLayout.tsx
|
||
│ │ ├── pos/POSHeader.tsx
|
||
│ │ ├── pos/ProductSearch.tsx
|
||
│ │ ├── pos/CategorySelector.tsx
|
||
│ │ ├── pos/QuickProducts.tsx
|
||
│ │ ├── pos/Cart.tsx
|
||
│ │ ├── pos/CartItem.tsx
|
||
│ │ ├── pos/CartTotals.tsx
|
||
│ │ ├── pos/CustomerSelector.tsx
|
||
│ │ ├── pos/DiscountPanel.tsx
|
||
│ │ ├── pos/PaymentModal.tsx
|
||
│ │ ├── pos/CashPayment.tsx
|
||
│ │ ├── pos/CardPayment.tsx
|
||
│ │ ├── pos/NumericKeypad.tsx
|
||
│ │ ├── pos/TicketHistory.tsx
|
||
│ │ ├── pos/RegisterSession.tsx
|
||
│ │ ├── pos/POSSettings.tsx
|
||
│ │ ├── pos/ConnectionStatus.tsx
|
||
│ │ └── ui/ # shared with apps/admin via component copy (TODO: extract to packages/ui in a future cleanup)
|
||
│ ├── features/
|
||
│ │ ├── auth/
|
||
│ │ ├── cart/ # POS cart state machine
|
||
│ │ ├── register/ # cash session state
|
||
│ │ ├── catalog/ # cached product list
|
||
│ │ └── hardware/ # adapter wiring
|
||
│ ├── lib/
|
||
│ │ ├── api-client.ts # typed client (mirror of apps/admin/src/lib/api-client.ts)
|
||
│ │ ├── permissions.ts # extends admin/permissions with POS_*
|
||
│ │ ├── money.ts # cents helpers, formatting (es-ES)
|
||
│ │ ├── tax.ts # client-side tax display only
|
||
│ │ ├── idempotency.ts # UUID v4 generator
|
||
│ │ └── hardware/ # adapter factories (browser impls)
|
||
│ ├── hooks/
|
||
│ ├── types/
|
||
│ └── middleware.ts # auth guard, terminal-id cookie
|
||
└── tests/
|
||
```
|
||
|
||
The app is delivered through the existing `monolith.sh` script (Phase 2: add a `pos` service on port 3006).
|
||
|
||
### 3.6 Multi-store inventory
|
||
|
||
Two options were considered:
|
||
|
||
- **(A) Extend `inventory_stock` with `store_id`** — chosen. Migration adds the column with a default "Main Store" UUID; backfills existing rows. Foreign key to new `stores` table.
|
||
- **(B) New `inventory_stock_by_store` table** — rejected: more moving parts, harder joins, no upside.
|
||
|
||
Operations:
|
||
|
||
- `inventory.reserve(variantId, storeId, qty)` becomes the signature.
|
||
- The POS endpoint always passes the terminal's storeId.
|
||
- Reporting endpoints (`GET /admin/inventory`) accept an optional `?storeId=` filter.
|
||
|
||
### 3.7 Authentication & authorization
|
||
|
||
- **Authentication:** identical to `apps/admin`. Same cookie, same `Authenticate` port. The POS app calls the same `/api/backoffice/auth/login` endpoint.
|
||
- **Authorization:** extend `shared/auth.ts` with `requireAnyRole(user, [...roles])`. New roles: `pos_cashier`, `pos_manager`. Permission string `POS_*` for fine-grained checks (override price, refund, cancel sale, open/close register).
|
||
- **Terminal identity:** a UUID generated on first boot of the POS app, stored in a Secure cookie (`pos_terminal_id`, 1 year expiry). The cookie survives reloads; clearing it requires re-binding the terminal to a record via a one-time admin code.
|
||
- **Session token in cookie** is the same as admin's. One user can be logged into admin and POS simultaneously (different cookies? no — same cookie, different apps).
|
||
|
||
### 3.8 Connection status / offline (deferred)
|
||
|
||
Phase 1–5: online-only. Connection status shows "● Online" / "⚠ Sin conexión" by pinging `GET /health` every 10 s.
|
||
|
||
Phase 8 (out of scope here): offline-first with IndexedDB queue and CRDT-style stock reconciliation. Deferred until the operator explicitly requests it. Architecture leaves a `pendingMutations` slot in the cart slice so it can be wired later.
|
||
|
||
---
|
||
|
||
## 4. Data model (full in `POS_DATA_MODEL.md`)
|
||
|
||
New tables (concise; full DDL in `POS_DATA_MODEL.md`):
|
||
|
||
| Table | Purpose | Key fields |
|
||
|---|---|---|
|
||
| `pos_stores` | Physical stores | `id, name, address, tax_id, settings_jsonb` |
|
||
| `pos_terminals` | One TPV device | `id, store_id, name, status, interface_mode, settings_jsonb, last_seen_at` |
|
||
| `pos_cash_sessions` | Open/close register | `id, terminal_id, store_id, user_id, opened_at, closed_at, opening_cash_cents, closing_cash_cents, expected_cash_cents, actual_cash_cents, difference_cents, status` |
|
||
| `pos_quick_products` | Favorite buttons | `id, store_id, terminal_id?, user_id?, product_id, variant_id, position` |
|
||
| `pos_parked_tickets` | Held tickets | `id, store_id, terminal_id, user_id, customer_id?, cart_jsonb, created_at, expires_at` |
|
||
| `pos_payment_methods` | Configurable payment types | `id, store_id, code, label, kind ('cash'\|'card'\|'other'), active, sort_order` |
|
||
|
||
Modified tables:
|
||
|
||
| Table | Change |
|
||
|---|---|
|
||
| `inventory_stock` | Add `store_id uuid NOT NULL DEFAULT <main store>`, FK to `pos_stores`. Replace unique index with `(variant_id, store_id)`. |
|
||
| `orders_orders` | Add `source text NOT NULL DEFAULT 'ecommerce' CHECK (source IN ('ecommerce','pos','admin'))`. Add `terminal_id uuid NULL`, `cash_session_id uuid NULL`. Add `COMPLETED` to state CHECK. |
|
||
| `backoffice_users.role` | Extend CHECK to include `'pos_cashier'`, `'pos_manager'`. |
|
||
|
||
No new customer/user table — POS sales link to existing `identity_users` (or NULL for walk-ins).
|
||
|
||
---
|
||
|
||
## 5. API surface (full in `POS_API.md`)
|
||
|
||
Mounted under existing Fastify via `registerPosRoutes(app, deps)` in `build-app.ts`. All under `/pos/...`. Reuses `requireRole` and `requireAnyRole` from `shared/auth.ts`. Cookie auth same as the rest.
|
||
|
||
| Method | Path | Purpose | Role |
|
||
|---|---|---|---|
|
||
| GET | `/pos/stores` | List stores | admin |
|
||
| POST | `/pos/stores` | Create store | admin |
|
||
| GET | `/pos/terminals` | List terminals | admin / pos_manager |
|
||
| POST | `/pos/terminals` | Register a terminal (returns binding code) | admin |
|
||
| GET | `/pos/terminals/me` | Current terminal by cookie | any pos |
|
||
| PATCH | `/pos/terminals/:id` | Update terminal settings | admin / pos_manager |
|
||
| GET | `/pos/sessions/me` | Current open session for terminal | any pos |
|
||
| POST | `/pos/sessions` | Open register | pos_cashier / pos_manager |
|
||
| POST | `/pos/sessions/:id/close` | Close register (counted cash) | pos_cashier / pos_manager |
|
||
| GET | `/pos/config` | Returns `{ terminal, store, session, paymentMethods, taxRates, categoriesTree }` | any pos |
|
||
| GET | `/pos/products/search?q=...` | Server-side search (delegates to catalog) | any pos |
|
||
| GET | `/pos/products/by-ean/:ean` | Direct lookup by EAN (fast path for scanner) | any pos |
|
||
| GET | `/pos/products/by-sku/:sku` | Direct lookup by SKU | any pos |
|
||
| GET | `/pos/quick-products` | Quick buttons for the current (terminal, user) | any pos |
|
||
| POST | `/pos/quick-products` | Add a quick product | pos_manager |
|
||
| DELETE | `/pos/quick-products/:id` | Remove | pos_manager |
|
||
| POST | `/pos/sales` | Create sale (idempotent) | pos_cashier+ |
|
||
| GET | `/pos/sales` | List recent sales (scoped to terminal/store) | any pos |
|
||
| GET | `/pos/sales/:id` | Sale detail | any pos |
|
||
| POST | `/pos/sales/:id/refund` | Refund (full or partial) | pos_manager |
|
||
| POST | `/pos/sales/:id/print` | Reprint receipt | any pos |
|
||
| POST | `/pos/parked-tickets` | Park current cart | pos_cashier+ |
|
||
| GET | `/pos/parked-tickets` | List parked tickets for store | pos_cashier+ |
|
||
| DELETE | `/pos/parked-tickets/:id` | Discard parked ticket | pos_cashier+ |
|
||
|
||
All POST/PATCH endpoints validate with `parseJson(zodSchema, body)`. All errors are `AppError`-shaped. All write actions append to `security_audit_log` via `AuditLogger.log`.
|
||
|
||
---
|
||
|
||
## 6. Reusable components
|
||
|
||
Existing modules reused as-is, no edits:
|
||
|
||
- `Authenticate` port, `parseJson`, `AppError`, `parseJson` (validation), `AuditLogger`.
|
||
- `OrderService` (with `source` extension), `InventoryService` (with `store_id` extension).
|
||
- `PricingService`, `TaxRateRepository`, `CatalogSearch`, `BrandRepository`, `CategoryRepository`, `ProductRepository`, `VariantRepository`.
|
||
- `CustomerRepository` from `users` for ticket association.
|
||
- `StoreSettingsRepository` for ticket header/footer.
|
||
|
||
Existing frontend utilities reused:
|
||
|
||
- `lib/api-client.ts` pattern (copy + extend with `posApi`).
|
||
- `lib/permissions.ts` extended with `POS_*` permissions.
|
||
- `AuthProvider` pattern copied and adapted (no shared package yet).
|
||
- Tailwind theme tokens (the `@theme` block in globals.css is identical).
|
||
|
||
---
|
||
|
||
## 7. Risks
|
||
|
||
| Risk | Severity | Mitigation |
|
||
|---|---|---|
|
||
| **Multi-store migration is destructive** | high | Migration backfills all existing rows with a single default store; reversible via SQL script kept in `scripts/`. Operator must approve before Phase 2 starts. |
|
||
| **Inventory race between POS and ecommerce** | high | All inventory writes go through `InventoryService.reserve/confirm`; same transaction model already used by checkout. Documented invariant: reservation is the only way to consume stock. |
|
||
| **`COMPLETED` state breaks existing admin workflows** | medium | State machine is additive; existing `DELIVERED` flow is unchanged. Admin orders stay on `DELIVERED`. POS-only orders end on `COMPLETED`. |
|
||
| **Cookie sharing between admin and POS apps** | low | Same domain; both apps read the same cookie. If POS is deployed to a different domain, swap to a JWT or shared session service (Phase 8). |
|
||
| **Idempotency conflicts** | medium | `idempotency_key` is already unique. The POS UI generates a UUID per "Cobrar" click; if the user clicks twice within ~50 ms, only one wins. |
|
||
| **Hardware fragmentation** | medium | All hardware behind adapters; no vendor SDK in core. Browser impls ship first (Phase 2/3); native bridge in Phase 7 only when operator commits to a vendor. |
|
||
| **Touchscreen keyboard** | low | React `NumericKeypad` component; no system-level dependencies. |
|
||
| **Refunds for split payments** | medium | Partial refund = multiple `payment_transactions` with negative `amount_cents`. Existing `payments` module already supports this. |
|
||
|
||
---
|
||
|
||
## 8. Phased plan
|
||
|
||
The brief already defines 7 phases. The list below translates them into Orquestra-friendly tickets:
|
||
|
||
| Phase | Ticket(s) | Goal |
|
||
|---|---|---|
|
||
| 0 | **POS-001** (this) | Discovery + architecture docs. |
|
||
| 1 | POS-002 to POS-010 | **Core TPV.** Schema migrations (stores, terminals, sessions, quick-products, parked-tickets, payment-methods). Multi-store inventory migration. `OrderService.source` extension. `COMPLETED` state. New `pos` module + routes + repository + unit tests. Frontend app skeleton with `POSLayout`, header, product search, categories, quick products, cart, totals. |
|
||
| 2 | POS-011 to POS-016 | **Checkout.** Cash payment (with change calculation), card manual entry, idempotent sale creation, stock decrement, receipt rendering, optional customer association, history. |
|
||
| 3 | POS-017 to POS-022 | **Cash register.** Open/close session, expected vs actual cash, difference capture, audit trail, end-of-shift summary. |
|
||
| 4 | POS-023 to POS-028 | **Multi-terminal.** Stores + terminals admin UI, terminal binding code flow, per-terminal quick products, per-store payment methods, concurrent terminals (already supported by HTTP). |
|
||
| 5 | POS-029 to POS-033 | **Touch UI.** Larger hit targets, virtual keypad, scanner auto-focus, keyboard shortcuts (F2/F4/F6/F8/F9/F10/ESC), responsive 1024×768 → 1920×1080, no horizontal scroll. |
|
||
| 6 | POS-034 to POS-040 | **Hardware.** Adapter interfaces finalized. Browser implementations complete. ESC/POS + USB scanner bridge behind a thin Node sidecar (out-of-process HTTP) — only the spec is written here; the bridge itself is built when the operator picks a vendor. |
|
||
| 7 | POS-041+ | **Polish.** Refunds UI, returns, partial refunds, gift receipts, scale integration, multi-currency (deferred to operator demand). |
|
||
|
||
Each phase ends with **all three gates approved (reviewer, security, qa)** and `verify.sh` exit 0.
|
||
|
||
---
|
||
|
||
## 9. Open questions for the operator
|
||
|
||
These are decisions the architect cannot take unilaterally and that block Phase 2:
|
||
|
||
1. ✅ **Default store name** — **RESOLVED**: "Natural - Mercado de Vida" (slug `natural-mercado-de-vida`).
|
||
2. ✅ **Cookie domain** — **RESOLVED**: separate port `:3006` for the POS app (alongside admin `:3004`). Cookie is set with `Domain` unset (so the browser scopes it to the POS origin only). When the operator deploys to production with Traefik and subdomains, the cookie strategy will be revisited (Phase 4 cleanup): at that point `Domain=.mercadodevida.example` allows admin and POS to share the same backoffice session.
|
||
3. ✅ **Touchscreen target hardware** — **RESOLVED**: 10-inch tablet in landscape. Responsive design from 1024×768 to 1920×1080, with a sensible tablet portrait mode (800×1280) as a stretch goal. The touch CSS uses media query `(pointer: coarse)` to detect and switch; manual override stored in cookie.
|
||
4. ✅ **Datáfono provider** — **RESOLVED**: stays manual in Phase 3. Phase 7 (`POS-038`) deferred — only reopens if the operator picks SumUp, Redsys TPVO, or Verifone.
|
||
5. ✅ **Refund policy defaults** — **RESOLVED**: refunds allowed up to 15 days after sale. Manager approval required for refunds above 50 € (configurable in `store_settings`).
|
||
|
||
The remaining questions (printer model, scanner type, cash drawer wiring, scale brand) are documented in `POS_HARDWARE.md §10` and resolved there.
|
||
|
||
---
|
||
|
||
## 10. Definition of done (Phase 1)
|
||
|
||
- ✅ This document (`POS_ARCHITECTURE.md`) signed off by leader.
|
||
- ✅ `POS_DATA_MODEL.md`, `POS_API.md`, `POS_HARDWARE.md`, `POS_OPERATIONS.md` exist with concrete specs.
|
||
- ✅ `POS_TASKS.md` lists P0–P3 prioritized tickets queued in the backlog (POS-002+).
|
||
- ✅ `verify.sh` exit 0.
|
||
- ✅ `runtime-status.json` reset to idle.
|
||
|
||
**No code is touched in this phase beyond the docs.**
|