mercadodevida/work/current.md

F-188 — POS pending payment orders and completion states

Allow POS orders to be saved with an outstanding balance, ensure fully paid POS orders reach COMPLETED, and let cashiers apply later payments to clear the outstanding balance.

Scope

• Backend validatePaymentAllocations accepts partial allocations (sum < total) without throwing POS_PAYMENT_TOTAL_MISMATCH. Overpayment remains rejected.
• POST /pos/sales persists orders with state='PENDING' when allocated total < order total, and state='COMPLETED' when allocations cover the order total.
• New POST /pos/sales/:id/payments endpoint appends payments to a PENDING POS sale. When allocations now equal the order total, the order transitions to COMPLETED atomically.
• Stock, reporting lines, payment lines and expected cash balance are updated by every payment, including rest-payment installments.
• Sale list exposes state, paidCents and outstandingCents. Cashier can fetch PENDING POS sales for the current session.
• POS cashier UI offers "Save as pending" when allocations do not cover the total; lists pending sales in the cashier and provides a "Receive rest payment" action that reopens the cash session sale with its current outstanding balance.
• Audit log records partial creation and pending fulfillment transitions.
• bounded shipments and refunds remain out of scope (F-189).

Out of scope

• Refunds, partial refunds and return tickets (F-189).
• Daily close reconciliation on top of pending balances (F-191).
• Customer credit, deposit or deposit-paper workflows.

Acceptance

1. Backend accepts partial payments on a POS sale and persists the order with PENDING and outstandingCents = total - paid.
2. Backend still marks fully paid POS orders as COMPLETED and rejects overpayment.
3. Pending POS sales appear in the cashier's session list with the outstanding balance.
4. Cashier can apply a follow-up payment to a PENDING sale; reaching the total transitions it to COMPLETED atomically.
5. Stock is reserved on POS sale creation (not on full payment) and reporting captures every partial payment.
6. Replaying the same idempotency key keeps the original order, its state and its payments intact.
7. Non-admin/non-POS users cannot create or modify pending POS sales.
8. Migration is reversible (or no migration is needed) and existing fully paid sales stay COMPLETED.
9. Tests, typecheck, affected builds and verify.sh are green.