freshyo/docs/test-cases/coupon-stacking-and-cart-guards.md
2026-10-15 20:31:20 +05:30

110 lines
8.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Coupon stacking, coupon list, cart discount label and checkout guards
Status: proposed checklist (NOT RUN). Covers the recently added behaviour only:
sequential coupon stacking (rounded to the nearest rupee, applied in the customer's
selection order), the cart coupon dropdown's visibility/ineligibility rules, the
cart "Products discount" row, the cart checkout guard for closed/unavailable
delivery slots, and the backend `create-user` script.
Priority and evidence rules follow the [catalog README](README.md). Money cases
must be checked on the **persisted** order and the order-detail response, not just
the cart preview — assert `goods − stored discount + delivery = payable` per
sub-order and in aggregate, with no negative/non-finite values.
Fixtures: reuse the shared fixtures (Regions A/B, A1/A2 bounds, coupons, slots
S1/S2 plus inactive/frozen/past, products P/Q/G, multi-slot cart). Use a second
isolated customer for ownership cases.
## Decisions these cases assume (now agreed)
- Coupons stack **sequentially on the remaining amount**, in the **order the
customer applied them** (chips shown in the same order).
- Each coupon's discount is **rounded to the nearest rupee** (`Math.round`); no
decimals on discounts.
- `maxValue` still caps **that** coupon's discount, computed on the reduced base.
- `minOrder` is validated against the **original** eligible subtotal (pre-discount).
- Hidden entirely: **expired**, **invalidated**, **usage-limit-exceeded**, and
**other users' personal** coupons.
- The checkout guard applies to **scheduled delivery only** (flash is exempt).
## A. Sequential coupon stacking (shared math + backend authoritative)
| ID | Priority | Action / input | Expected result |
|---|---|---|---|
| CSQ-01 | P0 | ₹1000 cart; apply 10% then flat ₹100. | Discounts 100 then 100 → 200; payable 800. |
| CSQ-02 | P0 | Same coupons, applied flat ₹100 then 10%. | 100 then 90 → 190; payable 810. Order changes the result. |
| CSQ-03 | P0 | 15% on ₹999. | Discount rounds to 150 (nearest rupee); payable 849, no decimals. |
| CSQ-04 | P0 | 10% then 20% on ₹1000. | 100 then 180 → 280; payable 720 (second uses the remaining). |
| CSQ-05 | P1 | Percentage with `maxValue` after a prior coupon. | Cap applies to its own reduced base (50% max ₹100 on ₹900 → 100). |
| CSQ-06 | P1 | Flat discount larger than the remaining eligible amount. | Discount clamped to remaining; totals never negative. |
| CSQ-07 | P1 | Targeted coupon (SKU X) then whole-cart coupon. | Targeted discount hits only X's line; the next coupon sees the whole cart's remainder. |
| CSQ-08 | P1 | Two targeted coupons overlapping on SKU X. | The second coupon's base excludes the first's discount on X. |
| CSQ-09 | P1 | Multi-slot cart with one coupon. | Per-sub-order shares sum exactly to the coupon discount; delivery charged once on the primary sub-order. |
| CSQ-10 | P0 | Place the order after stacking. | Cart preview = checkout = persisted `totalAmount` = order detail: `goods − discount + delivery`. |
| CSQ-11 | P1 | ≥100% coupon (e.g. 150%). | Goods never below zero; delivery may still be added; no negative totals. |
| CSQ-12 | P1 | Single coupon (regression). | Only change vs old behaviour is rounding to the nearest rupee. |
| CSQ-13 | P2 | Exclusive coupon combined with any other. | Combination rejected; exclusive applies alone. |
| CSQ-14 | P2 | Rounding exactly at `.5` (e.g. discount 149.5). | Rounds up (nearest rupee), consistently on client and server. |
## B. Coupon list visibility and disabled reasons (cart dropdown)
| ID | Priority | Action / input | Expected result |
|---|---|---|---|
| CLS-01 | P0 | Open the coupon dropdown on a populated cart. | Every coupon the customer may see is listed; applicable first, disabled last. |
| CLS-02 | P0 | Inspect a disabled row. | Row 1: CODE + italic **Disabled**; row 2: the reason. Not tappable. |
| CLS-03 | P0 | Coupon scoped to another region. | Shown disabled: "Not valid in your region". |
| CLS-04 | P0 | First-order-only coupon, customer already ordered. | Shown disabled: "Valid on your first order only". |
| CLS-05 | P1 | `minOrder` above cart subtotal. | Shown disabled: "Add ₹X more to use this coupon" (X = shortfall). |
| CLS-06 | P1 | Targeted coupon matching no cart items. | Shown disabled: "No applicable items in your cart". |
| CLS-07 | P0 | Expired coupon. | Not shown anywhere. |
| CLS-08 | P0 | Admin-invalidated coupon. | Not shown. |
| CLS-09 | P0 | Coupon whose per-user usage reached `maxLimitForUser`. | Not shown. |
| CLS-10 | P0 | Another user's personal coupon (U2 while logged in as U1). | Not shown. |
| CLS-11 | P1 | Eligible coupon. | Single line: `CODE - description (Save ₹x)`. |
| CLS-12 | P1 | "Save ₹x" with other coupons already applied. | Shows the **marginal** saving given the current selection (not standalone). |
| CLS-13 | P1 | Already-applied coupon in the dropdown. | Shows its own current contribution; selecting it is idempotent. |
| CLS-14 | P1 | Add then remove a coupon. | Remaining coupons re-sort (eligible first); disabled reasons recompute. |
| CLS-15 | P2 | Change region while the cart is open. | Region-mismatched coupons move to disabled with the reason; others update. |
## C. Cart "Products discount" row
| ID | Priority | Action / input | Expected result |
|---|---|---|---|
| CDIS-01 | P1 | Cart with market-price savings > ₹1. | Row label reads **Products discount** (was "Total Discount"). |
| CDIS-02 | P1 | Savings ≤ ₹1. | Row is hidden. |
| CDIS-03 | P2 | Coupons applied. | Coupon lines remain separate from the Products discount row; bill lines still sum to the total. |
## D. Cart checkout guard for delivery slots (scheduled delivery)
| ID | Priority | Action / input | Expected result |
|---|---|---|---|
| CGRD-01 | P0 | Item whose SKU has no entry in the slots file (or an empty list). | Checkout button disabled; error below: "Some items in your cart are no longer available for delivery…". |
| CGRD-02 | P0 | Item whose selected slot is no longer offered for it. | Checkout disabled; same "no longer available" error. |
| CGRD-03 | P0 | Item whose selected slot's freeze time has passed. | Checkout disabled; error: "The delivery slot for some items has closed…". |
| CGRD-04 | P0 | All items have valid, upcoming slots. | Checkout enabled; no error banner. |
| CGRD-05 | P1 | Out-of-stock item present. | Guard ignores OOS items (handled by the existing per-item badge); does not block on them alone. |
| CGRD-06 | P1 | Flash-delivery cart. | Guard does not apply; checkout remains enabled. |
| CGRD-07 | P1 | Recover by selecting a valid slot. | Guard clears immediately; checkout re-enables. |
| CGRD-08 | P1 | Tap the disabled button. | No navigation and no order created. |
| CGRD-09 | P2 | Error styling. | Red banner with icon directly below the action buttons. |
## E. Backend `create-user` script
| ID | Priority | Action / input | Expected result |
|---|---|---|---|
| USR-01 | P1 | `bun run create-user -- --mobile <m> --password <p> [--name --email]`. | Row in `users` + bcrypt row in `user_creds`; login (email or mobile) succeeds. |
| USR-02 | P1 | Repeat without `--update`. | Refuses ("already exists"); no duplicate rows. |
| USR-03 | P1 | Repeat with `--update`. | Password reset; login with the new password, old one rejected. |
| USR-04 | P2 | `--show-sql`. | Prints the SQL and exits without writing. |
| USR-05 | P2 | `--remote`. | Applies to the remote D1 (verify with a read). |
| USR-06 | P1 | Inspect the stored hash. | bcrypt `$2b$`/`$2a$`; `bcrypt.compare` accepts it. |
## Suggested automated coverage
- `apps/backend/tests/api/coupon-math.test.ts` — extend for CSQ-01/02/04 (order-sensitive), CSQ-03 (rounding), CSQ-10 (persisted parity); keep the single-coupon regression.
- `apps/backend/tests/api/coupon-ux.test.ts` — CLS-03/07/08/09/10 (what `getEligible` returns / omits).
- `apps/user-ui/tests/screens/cart-coupons.test.tsx` — CLS-01/02/11/12/13/14 (list order, disabled layout, marginal save).
- `apps/user-ui/tests/screens/cart-money.test.tsx` — CDIS-01 (label) and CSQ totals/rounding.
- `apps/user-ui/tests/screens/cart-screen.test.tsx` — CGRD-01..04, 07, 08 (button disabled/enabled + error text).
- `apps/backend/tests/api/order-flow.test.ts` / `order-rules.test.ts` — CSQ-10 persisted-money identity.
- Staging/manual — CGRD with real slot lifecycle (past/inactive/full), CLS-15 region switch, USR-02/03/05.