82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# 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`.
|