order-window-logic

# Order Window Logic ## Core concept Orders are governed by Fiji Airways flight windows, not a traditional always-open cart. The platform calculates order closing times by working backwards from flight departure. ## Flight schedule (current cadence) - **Frequency:** Weekly — one flight per week, every Thursday - **Route:** Labasa → Nadi (cargo transfer) → Sydney (Fiji Airways) - **Sydney → Riverina:** Freezer truck delivery, same day or next day - **FJT = UTC+12 | AEST = UTC+10 | FJT is 2 hours ahead of AEST** ## Order window cadence (weekly) | Day | Event | |-----|-------| | Friday 8:00am AEST | Order window opens (7 days before Thursday flight) | | Tuesday 5:00pm AEST | Order window closes — cousins receive summary | | Wednesday | Cousin packs orders (PACKING state) | | Thursday | Fish flown out (SHIPPED → IN_TRANSIT) | | Thursday/Friday | Delivered to Riverina buyers | **UTC equivalents (AEST = UTC+10):** - Friday 8:00 AEST = Thursday 22:00 UTC - Tuesday 17:00 AEST = Tuesday 07:00 UTC ## Timeline working backwards from Thursday flight 1. Fishermen catch: dawn to 2pm Wednesday 2. Cousin inspects + packs: 2pm–5pm Wednesday 3. Fish at Labasa airport: 5:30pm Wednesday (cargo cutoff) 4. Orders close: Tuesday 5pm AEST (~43h before cargo cutoff) 5. Orders open: Friday 8am AEST (6 days before flight) ## Order window states (state machine) ``` UPCOMING → OPEN → CLOSING_SOON → CLOSED → PACKING → SHIPPED → IN_TRANSIT → LANDED → CUSTOMS → DELIVERING → DELIVERED ↓ CANCELLED (any admin state) ``` - **UPCOMING:** window visible but not yet accepting orders (before Friday 8am) - **OPEN:** customers can browse + add to cart + checkout - **CLOSING_SOON:** 6 hours before close (≤ Tuesday 11am AEST), show urgency banner - **CLOSED:** no new orders; cousin receives order summary via WhatsApp/Telegram - **PACKING:** cousin confirms availability, adjusts quantities if needed - **SHIPPED:** fish on plane, customers notified with ETA - **IN_TRANSIT:** picked up at Sydney airport, in freezer truck to Riverina - **LANDED:** flight touched down - **CUSTOMS:** BICON biosecurity inspection - **DELIVERING:** out for delivery today - **DELIVERED:** customer receives fish; feedback prompt triggered - **CANCELLED:** admin manually cancelled window ## Fresh window concept `isFreshWindow` = window status is `open` AND `order_open_at` was less than 24 hours ago. Mutually exclusive with `closing_soon` — a window cannot be both fresh and closing. Used to show a "new order window just opened" banner variant so customers understand they're ordering for THIS week's Thursday delivery, not the previous shipment that already left. ## Shipment date labels Derived from `flight_date` in the shoppable window — NEVER hardcoded: - `shipmentDateLabel`: long form — "Thursday 24 April" (used in cart, checkout, order success) - `shipmentDateShort`: short form — "Thu 24 Apr" (used in fish card CTAs) Both are `null` when no shoppable window exists. ## Gotchas - Time zones matter: FJT vs AEST vs AEDT. Always store in UTC, display in user's zone. - AEST (UTC+10) applies May–October; AEDT (UTC+11) applies November–April - DST ends first Sunday in April; begins first Sunday in October - Flight cancellations: need a manual override to push window state back or cancel - Cousin confirmation: PACKING state requires explicit confirmation before SHIPPED - Partial availability: if cousin can only fill 70% of orders, admin must contact affected customers - Never auto-transition to SHIPPED without cousin confirmation - isFreshWindow and isClosingSoon are mutually exclusive by design