mercadodevida/work/artifacts/POS-001/implementer.md

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.