| name | order-window-logic |
| description | Flight-driven order window business rules. Use when building or modifying order lifecycle, window state transitions, closing time calculations, or any logic involving Fiji Airways timetable and order cutoffs. |
| allowed-tools | Read, Grep, Glob |
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
- Fishermen catch: dawn to 2pm Wednesday
- Cousin inspects + packs: 2pm–5pm Wednesday
- Fish at Labasa airport: 5:30pm Wednesday (cargo cutoff)
- Orders close: Tuesday 5pm AEST (~43h before cargo cutoff)
- 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
