FIRST JACK V7 — CUSTOMER HISTORY, CART RECOVERY AND COUPONS

WHAT'S INCLUDED
- Coupons sidebar: fixed/percentage discounts, expiry date, minimum product subtotal, discount cap, total usage limit, activation and optional checkout-exit offers. Leave the use limit at 0 for unlimited repeat usage.
- Checkout coupon input with server-verified discounts and receipt totals. Leaving checkout via Close, Escape or backdrop displays the newest eligible exit coupon, with Copy, Continue and Leave actions. Browser tab closure cannot display a custom offer. No offer appears when no eligible coupon is enabled.
- Coupon redemption is transactional and recorded once per order, including safe retry handling. Discounts apply to products, not delivery.
- Floating recent-order bubbles with an upward animation, alternating left/right placement, a close action, and reduced-motion support. These show real website orders with masked customer names.
- Saved-cart reminder when the same shopper returns in the same browser. Cart items, quantities, sizes, name, phone, address, delivery area and notes survive page reloads and unfinished checkout.
- Multiple separate orders from the same unblocked IP. The former 20-orders-per-hour IP cap is removed. Retrying the same submitted checkout still creates just one order.
- Customers sidebar section: customer names, numbers, addresses, products/sizes/quantities, order and checkout dates, full customer history and recorded IPs.
- Customer date filters and Excel exports for 1, 3, 7 days; 1, 3 months; 1, 2 years; all years; yesterday; a specific date; or a custom date range.
- Excel downloads include ALL matching records across every page. One row represents one order or checkout, with products listed together. Phone numbers stay as text; dates, quantities and amounts are numeric. The header is frozen and filtered.
- Customer IP block/unblock buttons, shared with Orders and Pending Checkouts. IPv6 spelling is normalized. Cloudflare client IP is accepted only when the connecting server is in verified Cloudflare ranges; arbitrary forwarded headers are ignored.
- Compact green Call buttons on the right in Orders, Pending Checkouts, Customers and customer history. The previous oversized unstyled SVG is fixed.
- Durable customer snapshots are backfilled from existing orders and checkout records. Converted checkouts stay stored but are excluded from the visible counts/exports to avoid counting their order twice. Snapshots survive later source-order deletion.

UPLOAD TO YOUR EXISTING HOSTING
Back up your website and database first. Keep your LIVE ai/.env, ai/config/db.php, .htaccess and uploaded product/branding files.

Upload the following storefront files:
  index.html
  theme-enhancements.js
  theme-enhancements.css
  assets/ (merge; do not delete existing live uploads)

Upload these changed/new admin files, preserving their paths:
  ai/index.php
  ai/assets/js/app.js
  ai/assets/js/coupons.js
  ai/assets/css/coupons.css
  ai/api/coupons.php
  ai/config/coupons.php
  ai/assets/js/customers.js
  ai/assets/css/customers.css
  ai/api/customers.php
  ai/api/ip_block.php
  ai/api/storefront.php
  ai/api/orders.php
  ai/api/website_pending.php
  ai/config/storefront_security.php
  ai/config/customer_archive.php
  ai/config/customer_excel.php
  ai/migrate_customers.php

The archive tables initialize automatically. To explicitly backfill history after upload, sign in to the admin panel and open ai/migrate_customers.php once. Or run php ai/migrate_customers.php on the server. Existing orders are preserved. The database account needs its normal CREATE/ALTER rights.

Purge hosting/CDN cache once, then open the storefront with ?v=7. Customers and Coupons share the existing Orders permission; no new staff permission setup is required.

PROXY NOTE
Cloudflare is detected automatically. For a different reverse proxy, add STOREFRONT_TRUSTED_PROXIES="your-proxy-IP-or-CIDR" to the LIVE ai/.env, using commas for multiple entries. Do not list arbitrary public clients. Old records cannot recover IPs that were never captured accurately; new orders and checkouts use the corrected detection. Unblock any previously blocked shared proxy IP before testing.

DATA AND DATES
Date filters use Bangladesh local calendar dates. Day ranges include today and the preceding N-1 days. Month/year ranges use rolling calendar periods with month-end clamping. Custom date ranges include both selected dates.
Checkout amounts are estimated product subtotals; order amounts are the recorded order totals. Excel marks the amount type explicitly. Checkout records appear in history as unfinished/dismissed checkouts until converted.
Browser cart recovery requires the same browser's saved website data. Clearing that data or switching devices prevents local cart recovery.

VALIDATION
PHP 8.3 / MariaDB 10.11 integration checks passed against an isolated test database: repeat orders from one IP, idempotent retries, block/unblock enforcement, auth restrictions, normalized IPv6, trusted proxy handling, customer snapshots, all date-period boundaries, custom dates, invalid dates, genuine XLSX output, and mixed database collations.
Chromium checks passed at widths 320, 390, 768 and 1440 for Customers and Pending Checkouts, and at 390 for returning-shopper recovery, two separate browser orders on the same IP, cart clearing and alternating order bubbles. The Excel ZIP/XML, numeric/date cells, text phone numbers, Bengali text, filters and frozen headers were checked. QA images use test data.
Coupon backend checks cover fixed/percent discounts, caps, usage limits, expired/unknown codes, transactional rollback and idempotent redemption. Coupon browser checks at 320, 390, 768 and 1440 cover creation, exit offer, copying, applying, discounted receipt and horizontal overflow.
These are local browser/database checks, not a physical iPhone test or a check of your live hosting.

REBUILD THE STOREFRONT
cd source/storefront
npm ci
npm run build
python3 scripts/package-storefront.py
Then upload the generated storefront root files and assets/.
