31 lines
2.4 KiB
Markdown
31 lines
2.4 KiB
Markdown
# 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.
|