mercadodevida/work/artifacts/POS-008/architect.md

POS-008 — Architect

Feature

POS Phase 1 ticket 008: POST /pos/sales idempotent transaction.

Objetivo

POST /pos/sales: creates a POS sale atomically (order + line items + payments + cash session update) in a DB transaction. Idempotent via idempotency key.

Diseño

• CreatePosSaleUseCase takes: idempotencyKey, cashSessionId, terminalId, userId, items[], payments[]
• Step 1: idempotency check (return existing if key found)
• Step 2: verify cash session OPEN (FOR UPDATE lock)
• Step 3: compute totals
• Step 4: INSERT order
• Step 5: INSERT line items
• Step 6: INSERT payments + update cash session expected_cash_cents
• All in BEGIN/COMMIT/ROLLBACK transaction
• Provider types: pos_cash, pos_card, pos_other (not regular payment providers)