Business Workflows¶

Shipment Lifecycle¶

1. Creation¶

User creates shipment
    ↓
Shipment created with status RECEIVED
    ↓
Packages added to shipment (1 or more)
    ↓
If all packages same recipient → Shipment.recipient_id set
If different recipients → Package.recipient_id set per package

2. Bag Assignment¶

Shipment ready for bagging
    ↓
Operator assigns shipment to bag (BagAssignment)
    ↓
Shipment status → PACKING
    ↓
Courier transports bag to airport
    ↓
Bag status → TO_AIRPORT

3. Flight¶

Bag on flight
    ↓
Bag status → IN_FLY
    ↓
Flight status tracked via webhook (AeroDataBox)
    ↓
Bag arrives at destination airport
    ↓
Bag status → IN_AIRPORT

4. Delivery¶

Bag with courier for delivery
    ↓
Bag status → WITH_COURIER
    ↓
Package status updates as delivered
    ↓
Shipment status → DELIVERED

Status Transitions¶

Shipment Status Values¶

Status	Description	Valid Transitions
RECEIVED	Just created	→ PACKING, CANCELLED
PACKING	Package(s) assigned to bag	→ PACKED, TO_AIRPORT
PACKED	All packages packed	→ TO_AIRPORT, RETURNED
TO_AIRPORT	In transit to origin airport	→ IN_FLY
IN_FLY	On the flight	→ IN_AIRPORT
IN_AIRPORT	Arrived at destination	→ WITH_COURIER, IN_WAREHOUSE
WITH_COURIER	Courier has the bag	→ DELIVERED
IN_WAREHOUSE	In destination warehouse	→ WITH_COURIER
CONSOLIDATING	Consolidating packages	→ CONSOLIDATED
CONSOLIDATED	Consolidation complete	→ WITH_COURIER
DELIVERED	Completed	(terminal)
RETURNED	Returned to sender	(terminal)

Package Status Values¶

Status	Description
CREATED	Registered in system
PACKED	In a bag
IN_TRANSIT	Moving with courier
DELIVERED	Delivered
RETURNED	Returned

QR Scan Workflow¶

Courier scans QR code
    ↓
System validates:
    1. QR format correct (hmac_valid)
    2. QR belongs to tenant (wrong_tenant check)
    3. Package exists (entity_not_found)
    4. Rate limit not exceeded (< 100/hour)
    ↓
If valid → Scan recorded, status updated
If invalid → Error returned, logged

Warehouse Receiving¶

Shipment arrives at warehouse
    ↓
Operator receives shipment
    ↓
PackageReceivedEvent created
    ↓
Condition checked (good, damaged)
    ↓
If damaged → BagIncidence reported

Flight Alert Subscription¶

User subscribes to flight updates
    ↓
System registers webhook with AeroDataBox
    ↓
Flight status changes → webhook sent
    ↓
System processes webhook
    ↓
Shipment/bag status updated