# POS-001 — Implementer notes: Discovery & Architecture

## Status

Phase 1 (Discovery) only. No code was written. The deliverable is **5 architecture documents** under `docs/pos/`.

## Documents produced

| File | Lines | Purpose |
|---|---|---|
| `docs/pos/POS_ARCHITECTURE.md` | ~480 | Executive summary, current stack analysis, gap analysis, proposed architecture, multi-store strategy, hardware abstraction, phased plan, open questions, definition of done. |
| `docs/pos/POS_DATA_MODEL.md` | ~410 | Every new table (DDL + constraints), every modified table (ALTER), seed data, FK/CK/unique index strategy, entity-relationship diagram, migration plan (043–046), parked-cart JSON shape, audit action keys, indexes summary. |
| `docs/pos/POS_API.md` | ~310 | Every HTTP endpoint (`/pos/*` and `/pos/admin/*`), request/response DTOs, status codes, validation rules, discount limits, rate limits, error envelope. |
| `docs/pos/POS_HARDWARE.md` | ~280 | Adapter interfaces, browser implementations (scanner/printer/cash-drawer), native bridge strategy, configuration model, vendor-neutral philosophy, open questions. |
| `docs/pos/POS_OPERATIONS.md` | ~290 | Deployment, daily ops (open/sell/close), roles & permissions, monitoring, failure modes & troubleshooting, rollback plan, security notes, backup & DR, smoke test, runbooks. |
| `docs/pos/POS_TASKS.md` | ~470 | 46 tickets (`POS-002` through `POS-046`) split across 7 phases, each with rationale, scope IN/OUT, touches, acceptance criteria. Prioritized P0/P1/P2/P3. |

## Backlog populated

- `POS-001` (this ticket): in progress, then done.
- `POS-002` through `POS-010`: Phase 1 (Core TPV). 9 tickets.
- `POS-011` through `POS-022`: Phase 2 + 3 (Checkout + Cash register). 12 tickets.
- `POS-023` through `POS-033`: Phase 4 + 5 (Multi-terminal + Touch UI). 11 tickets.
- `POS-034` through `POS-046`: Phase 6 + 7 (Hardware + Polish/future). 13 tickets.

Total queued: 45 tickets. Distribution by priority:

- **P0 imprescindible**: 16 tickets
- **P1 importante**: 18 tickets
- **P2 mejora**: 9 tickets
- **P3 futuro**: 6 tickets

## Key architectural decisions captured

1. **POS sale = order with `source='pos'`** — no parallel order system.
2. **Multi-store inventory** — `inventory_stock` gains `store_id`; default store seeded in migration 043.
3. **`COMPLETED` order state** added — POS sales skip `SHIPPED`/`DELIVERED`.
4. **`orders_orders.user_id` becomes nullable** — walk-in sales allowed; CHECK enforces rules.
5. **Backoffice roles extended** — `pos_cashier`, `pos_manager` added to the role CHECK.
6. **Adapter interfaces** for hardware — zero vendor SDKs in core. Browser impls ship first.
7. **Idempotent sale creation** — same `idempotencyKey` returns the same order.
8. **Atomic sale flow** — pricing → reserve → create order → register payments → confirm stock → mark COMPLETED in a single PG transaction.
9. **Hardware abstraction**: scanner/printer/cash-drawer/payment-terminal/scale adapters behind narrow interfaces. Browser implementations for Phase 2/3; native bridge deferred to Phase 7 only when operator commits to a vendor.
10. **Same cookie domain** as the admin app for shared session.

## Reuse over rewrite

No existing module is being forked or rewritten. Every POS concept either:

- **Reuses an existing module directly** (auth, pricing, inventory, orders, payments, catalog, users, audit, telemetry, store-settings).
- **Adds a thin new module** (`pos`) that consumes the existing ports via injection.
- **Extends an existing table or enum** in a backwards-compatible way (additive `source`, additive `COMPLETED`, additive roles).

The only "breaking" change is `inventory_stock` gaining `store_id` (unique constraint + indexes change). This is mitigated by backfilling all existing rows with the default store UUID before the constraint is added.

## No code changes

This ticket does not commit any code. The next ticket (`POS-002`) is the actual schema migration.

## Open questions for the operator (from POS_ARCHITECTURE.md §9 and POS_HARDWARE.md §10)

These block Phase 2 implementation:

1. Default store name (suggested: "Mercado de Vida — Tienda principal").
2. Cookie domain strategy (same origin as admin? subdomain?).
3. Touchscreen minimum target hardware.
4. Datáfono provider (none for Phase 3; SumUp / Redsys TPVO / Verifone for Phase 7).
5. Refund policy defaults (within X days, manager approval above Y €).
6. Printer model for ESC/POS (Epson, Star, Citizen).
7. Scale brand if any.
8. Cash drawer wiring (printer kick-out vs separate port).
9. Scanner type (HID-only vs serial/USB-HID native).

## Definition of done (Phase 1)

- ✅ 5 architecture docs exist under `docs/pos/`.
- ✅ 45 implementation tickets queued in `backlog/features.json`.
- ✅ `verify.sh` exit 0.
- ⏳ Operator sign-off on the 5 docs.
- ⏳ Operator answers the 9 open questions.
- ⏳ Leader promotes POS-002 (schema migrations) to `in_progress`.