01 · Hero

Logistics is the team that turns freight intent into actual shipments. They open this queue daily, work through pending reviews, pick carriers, schedule pickups, generate BOLs, capture tracking, handle issues. This workflow gives them a structured queue with everything they need to act — no re-reading the source SO/PO, no hunting for ship addresses, no guessing the freight class.

02 · What this is

A v2 workflow contract that fires when a record lands on the logistics review queue (output of freight_routing_check). 7 stages: review → carrier select → pickup schedule → BOL generate → tracking capture → verify +24h → verify +7d.

03 · When it fires

Triggered by freight_routing_check when its flag_for_logistics_review step lands a proposed_actions row. Once Mike (or logistics lead) approves the routing, this workflow advances through its 7 stages with HITL gates at carrier selection, pickup schedule, and BOL generation.

04 · Step-by-step

Logistics team review — confirm classification, check address, item weights, special handling. Escalate if anything mis-classified.
Select carrier — based on classification + lane history. HITL-approved.
Schedule pickup — once freight is ready (IF/IR created or assembly built), write pickup datetime to NS.
Generate BOL — PDF using GFS standard template. Includes customer PO# threading.
Capture tracking + notify owner — tracking number stored on record, owner emailed, customer emailed if SO.
Verify tracking active (+24h) — carrier API confirms picked up. Else escalate.
Verify delivery confirmed (+7d) — POD captured to R2, freight_status=delivered, reflexion writes lane score.

05 · Outcomes

SO/PO ships on time with the right carrier for the lane
BOL has the customer PO# so the customer can trace it on their end
POD is captured + stored, closing the audit loop
Lane history score updated for next freight check on the same lane
Universal Finance handoff fires (delivered → invoice ready)

06 · Failure modes

Mode	Trigger	Recovery
Pickup missed	verify +24h fails OR carrier no-show	Re-schedule, log lane reliability penalty
Delay in transit	tracking no movement > 48h	Carrier call, customer pre-notify, ETA update
Damage on delivery	POD notes damage	Open carrier claim, document, replacement order
Refused delivery	Carrier returns shipment	Investigate cause, hold inventory, escalate to sales
Lost shipment	tracking stuck > 7 days	Formal loss claim, ship replacement

07 · Related

08 · For developers

workflow_type: logistics_review_workflow
risk_level: 2
trigger: freight_routing_check.flag_for_logistics_review approval
inputs_required:
  source_record_id: number
  source_record_type: ['so', 'po']
  classification_from_check: ['LTL', 'FTL', 'parcel', 'dropship_vendor_freight', 'customer_pickup', 'freight_collect']
context_to_load:
  - full source record (SO or PO)
  - customer_or_vendor_address
  - prior_freight_history (same lane, last 90 days)
preconditions:
  - classification present
  - source record in correct status (IF created OR IR received)
fan_out_targets:
  - logistics_team_review (hitl_email_draft)
  - select_carrier (stage_proposed_action)
  - schedule_pickup (stage_proposed_action)
  - generate_BOL (stage_proposed_action)
  - capture_tracking (chat_tool)
  - notify_so_or_po_owner (hitl_email_draft)
  - update_freight_status (d1_write)
post_actions:
  - log_run
  - reflexion (updates lane_history scores)
  - event(logistics.shipment_scheduled)
  - event(logistics.shipment_delivered) on +7d verify pass
verify_checks:
  - tracking_active (+24h post pickup)
  - delivery_confirmed (+7d post pickup)

09 · Changelog

Date	Round	Change	By
`2026-05-26`	`R594`	Built initial logistics review workflow. Dashboard URL `https://gfs-netsuite.pages.dev/logistics-review.html` flagged TBD pending build.	Mike + Claude

10 · Schema (PO# threading)

Record	Field	Carries
Logistics queue entry	`source_po_or_otherrefnum` (mirrored)	From SO.otherrefnum or PO.memo
BOL	`shipper_ref`	= source_po_or_otherrefnum — customer sees their PO# on their end
Tracking row	`tracking_number` + `carrier`	Written back to source SO/PO as `custbody_tracking_number` TBD field name
POD	`pod_url` (R2)	Written back as `custbody_pod_url` TBD field name
Delivery event	`event_ledger.payload.po_or_otherrefnum`	Triggers Finance handoff with PO# context

11 · Runbook

Daily logistics flow:

1. Open https://gfs-netsuite.pages.dev/logistics-review.html (TBD URL)
2. Sort by pickup_scheduled (oldest first)
3. For each "pending review" row: confirm classification, click into source record, then stage carrier
4. For each "scheduled" row past pickup: verify tracking active
5. For each "in transit" past delivery ETA: verify POD or escalate

Manual issue escalation:

POST /api/workflow/run
{ "workflow_type": "logistics_review_workflow", "inputs": { "source_record_id": 12345, "issue_type": "delay" } }

12 · Backlog

TBD Build the logistics dashboard at https://gfs-netsuite.pages.dev/logistics-review.html
TBD Mike confirms NS custom fields: custbody_tracking_number, custbody_pod_url, custbody_carrier
Carrier rate card integration — today freight cost is manual
Lane history scoring with reflexion writeback — needs logistics_lane_scores D1 table
Customer-facing tracking page accessible by customer PO#
Hazmat workflow split-out — DG declarations + carrier whitelist
Real-time tracking webhook from carriers (UPS, FedEx, LTL aggregators)