order-window-logic

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

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