Every facility raises a GRN — the goods changed hands, whether or not anyone
stores them. What differs is what happens next: Indode has a warehouse, so cargo
left there goes through the existing warehouse flow and accrues storage and
demurrage; Sebeta, Modjo, Adama and Dire Dawa only move cargo between train and
truck, so the handling event and its GRN are the whole record.
facility_handling_events carries that record because warehouse_inventory cannot:
its warehouse/yard/zone are NOT NULL, so a facility with equipment but no
warehouse could never have a row there. inventory_id links the storage record
when the facility does keep the cargo, which is what ties an Indode handover to
its demurrage.
generateGrnNumber moves to common/grn.util.ts so a GRN raised at a facility is
indistinguishable from one raised in a warehouse — the two live in different
tables, and a second generator would let the formats drift.
Recording is best-effort: the cargo moved regardless, so paperwork must never
fail the journey.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The previous commit made autoUnloadArrived and unloadBooking raise a GRN for any
direction, which changed import behaviour. Import keeps its own GRN handling
(autoUnloadArrivedBookings) and is left exactly as it was. Both paths now stamp a
GRN only when the booking is EXPORT — the direction whose cargo needs one to be
loaded onto a train. Import and domestic behave as before.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Requiring a GRN before loading only works if every path into the warehouse
issues one. Two did not: autoUnloadArrived and unloadBooking created RECEIVED
inventory with a null grn_number, so cargo that genuinely arrived — by first
mile or self haul — would have been stuck un-loadable behind the new gate.
Both now stamp a GRN, derived from the booking's trade direction, matching
receive/bulkReceive/autoUnloadArrivedBookings. unloadBooking keeps an
already-issued GRN when it re-unloads an existing row rather than reissuing one.
Every path that creates warehouse inventory now issues a GRN, so the chain is
seamless: booking arrives (first mile or self haul) -> received -> GRN -> loadable
onto its allocated wagon.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The export chain is: paid -> received into the warehouse -> GRN raised on arrival
-> loaded onto the allocated wagon. Receipt was already structural (the inventory
row only exists once receive() runs) and the wagon was already required, but the
GRN was merely displayed, never enforced — so cargo could be loaded and
dispatched without one.
- loadable now also requires a GRN, so the queue won't offer un-GRN'd cargo.
- loadItemsOntoTrain skips items with no GRN, so the rule holds server-side and
a hand-made API call can't bypass it.
- Read the GRN from inv.grn_number (what receive() stamps) and fall back to the
note only for legacy/seeded rows; it previously read the note alone, which the
real receive path merely mirrors.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
dispatchSchedule guarded status, Djibouti departure rules, locomotives and
wagons — but never checked the cargo. A train could be dispatched while the
bookings allocated to it sat received in the warehouse, silently leaving them
behind. Dispatch now refuses when an allocated booking has warehouse inventory
in RECEIVED/STORED/READY_FOR_LOADING, naming the bookings and pointing at the
two ways out: load them, or drop the wagon allocation so they ride a later
train. Bookings with no inventory at all are not blocked — allocating a wagon
before the goods arrive is normal planning.
Also drops RESERVED from the Load-to-Train filters: reserved stock is not
awaiting loading.
The sched_bookings CTE moves to common/schedule-bookings.sql so the warehouse
loading queue and this dispatch guard resolve a train's bookings identically —
if they drift, a train departs leaving cargo the warehouse still expects to load.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Load-to-Train queue was permanently empty for real traffic. loadableTrains()
and trainLoadableItems() gated on freight.train_schedule_bookings, but nothing in
the application writes that table — only the demo seeders do. Real wagon
allocation writes wagon_booking_allocations, reached via
train_schedules -> train_sets -> train_set_wagons, so an allocated export booking
never satisfied the EXISTS gate and no train ever appeared.
Both queries now resolve a schedule's bookings through a shared sched_bookings
CTE that unions the wagon-allocation chain with train_schedule_bookings, so real
allocations show up and the seeded demo scenarios keep working. The panel already
groups the returned rows by booking with their containers, so the queue now lists
the train, its bookings and their containers for selection.
Export flow this serves: booked -> paid -> received at the warehouse (first-mile
or self-haul) -> GRN -> loaded onto the wagons allocated to the booking.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EDR last-mile is multi-truck but was modelled as one: setVehicles accepted any
number of trucks with no validation, arrival/delivery were stamped once per
last_mile record (N trucks shared one timestamp), EDR trucks got no exit paper,
and the per-truck EDR handover never happened because deliver() resolved the
plate via last_mile_container_allocations — a table nothing writes.
- Migration 2260000000000: per-truck arrived_at/departed_at/gross_weight_tons/
net_weight_tons on last_mile_vehicle_assignments, plus a
last_mile_vehicle_containers child table (a truck holds 1x40ft OR 2x20ft, so
the single container_number scalar could not express a load). Weights are
TONNES and named accordingly — the older gross_weight_kg lies about its unit.
- setVehicles: enforce the size rule (one 40ft, or two 20ft), container
membership, one-container-one-truck, and never more trucks than containers.
Bulk carries no containers and is instead gated on tonnage remaining.
- Bulk drawdown: remainingTonsForBooking = booking VGM minus the net weighed off
every departed truck (both tonnes, no conversion), exposed as
GET /last-mile/booking/:bookingId/remaining-tons.
- release() now stamps the EDR truck's own arrival and exit (matched by plate, so
it works for bulk too) alongside the existing customer-truck stamp. The exit
weighing itself is untouched.
- New GET /warehouse-inventory/edr-truck-exit-paper/:assignmentId — per-truck
exit paper for EDR trucks. Deliberately not signature-gated: EDR handovers are
generated at delivery, after the truck has left.
- deliver(): resolve the handover plate from the truck's own containers instead
of the dead allocations table, so EDR handovers are genuinely per-truck.
- Notify the customer (portal inbox + SMS/email) when a truck leaves — one hook
in release() covers both self-haul and EDR, since it is the single exit path.
Self-haul is intentionally unchanged (one booking-level handover signed once).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add actorLabel(user) — resolves the authenticated user to a readable name
(name → username → email → id) — and use it for the performed_by audit stamp on
every warehouse action, so the activity log shows a person, not a UUID. The
freight DB has no users table to join, so the name is stamped at write time.
approve-delivery keeps the raw user id (it is an id argument, not the audit
label). Existing rows keep their prior value; this applies going forward.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Warehouse mutation endpoints now record the JWT-authenticated user as the actor
(user.id) instead of trusting a client-supplied performedBy string, unlocking
per-operator productivity metrics and a trustworthy audit trail. Covers receive,
receive-bulk, reserve, store, ready-for-loading, ready-for-pickup, load-onto-
train, bulk-dispatch, dispatch, deliver, gate-clearance, approve-delivery, the
Djibouti/import auto-unload actions, and fee-invoice generation. The prior
client value is kept only as a fallback for unauthenticated/internal calls.
move/load do not yet carry an actor (their DTOs have no performedBy) — separate
follow-up.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- gateStats(): items cleared through the gate today, average arrival→gate
turnaround (hours, 30d), and clearances per hour over the last 24h → new
GateThroughputCard in the dashboard Performance section.
- Live board: every dashboard query (dashboard, ops, throughput, dwell, cycle,
on-time, zone occupancy, accrual, gate) now auto-refreshes on a 60s interval,
with a "Live" indicator in the header.
New endpoint GET /warehouse-inventory/gate-stats (guarded). Deferred (need
upstream data): capacity forecast, labour productivity, WebSocket push, yard map.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds the operational-performance layer to the warehouse cockpit:
- Dwell time & aging: dwellStats() (avg + 0-3/4-7/8-14/15+ buckets over
in-warehouse items) → DwellAgingCard histogram.
- Cycle time & on-time: cycleStats() (arrived→ready→loaded→dispatched stage
averages + dock-to-dispatch) and onTimeDispatchStats() (share of items that
left before their storage free-days expired, resolved via the fee engine's
own rule matching) → CycleTimeCard.
- Live tiles: opsStats() now returns receivedYesterday; KpiStrip renders an
optional ▲/▼ delta, and the ops strip shows received-today vs yesterday.
New endpoints: GET /warehouse-inventory/{dwell-stats,cycle-stats} and
/warehouse-fees/on-time-dispatch (all guarded). New "Performance" section on
WarehouseDashboardPage. On-time reads N/A when there is no sample / no active
storage rule.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- WarehouseDashboardPage now composes the ops KPI strip, lifecycle cards, flow
charts, zone-occupancy heatmap and demurrage/accrual exceptions into one
control-tower view; drop the redundant lifecycle donut.
- New GET /warehouse-inventory/throughput (date_trunc time series) replaces the
client-side buildTrend that downloaded the entire inventory list to bucket it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Truck loading:
- loadTruck enforces max 2 containers / one 40ft (two 20ft) and auto-marks an
assigned truck arrived on load; container-items payload + modal expose
container size with a client-side selection cap.
- Show "#x containers pending assignment" in the portal truck card and the
backoffice container modal.
Last-mile:
- create() is idempotent — return the existing record for a booking instead of
inserting a duplicate delivery row (fixed the same booking showing twice in
Assign-Mile).
- setVehicles/update reject a truck with no assigned driver; the Assign toast
now surfaces the reason.
- New GET /last-mile/booking/:id/arrival-trucks returns assigned EDR trucks with
driver details; ReleaseOrderModal fetches and auto-fills them so an assigned
EDR truck no longer reads as "not assigned yet".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Truck Arrival died with "[@mantine/core] Duplicate options are not supported"
when a booking carried the same container number on two container lines (the
unit uniqueness is per line, not per booking):
- bookingContainerWeights now GROUPs BY container number (MAX weight)
- the weighing modal dedupes both the containers MultiSelect and the
assigned-trucks Select defensively, so bad data degrades instead of
crashing the whole page
Import GRN is now issued automatically when the arrived train is unloaded:
autoUnloadArrivedBookings stamps GRN-IMPORT-<date>-<booking> on both the
create and update paths (never overwrites an existing GRN). The per-row GRN
button in the import queue lights up with no extra clicks.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
"Auto Load Ready Items" now opens a train picker (pre-dispatch trains with
these bookings assigned, via the existing loadable-trains flow). No train
available -> no auto-loading, with a clear notice. Loading goes through the
existing per-wagon load path, so items without an allocated wagon are skipped
with a reason.
The train association is stored on the existing warehouse_loadings table
(no new table needed): new train_schedule_id column + a note recording train
number, origin -> destination, and departure time; wagon_id becomes nullable.
The trainless load-passed-export endpoint, its frontend wiring, and the unused
useLoadPassedExport hook are removed.
Migration 2100000000000 (idempotent) also applied to the dev database.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- remove Incoterms, HS codes, and Item code from the truck-entrance form:
nothing in the booking captures them, so they were always hand-typed noise
- remove the hand-typed "Warehouse code and location" input: the backend now
stamps it from the warehouse/yard/zone the operator actually selected
(WH / YARD / ZONE codes), so the GRN and notes always match reality
- Declaration number and Item description widen to full rows
Backend DTO keeps the optional fields for compatibility.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The receive form now arrives filled with everything the booking already knows,
instead of the operator re-typing it:
- container numbers come from the per-unit records (booking_container_units)
entered at booking time, falling back to the line-level aggregate
- customs seal number prefilled from the units' seal numbers
- net weight prefilled from the booking's declared cargo weight (tonnes)
- driver signatory defaults to the arriving driver's name
Existing prefills (owner, TIN, phone, booking ref, cargo, packaging, unit
count, first-mile / customer truck + driver) unchanged; all fields stay
editable where they were editable before.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Approve delivery now tracks the handover lifecycle exactly: the button appears
(detail page + portal dashboard) the moment a handover is generated and
disappears when the customer signs. The bookings list attaches the
handoverAwaitingSignature flag via one batched query per page; status
heuristics (COMPLETED / TRUCK_ASSIGNED+arrived) are gone.
- generate the arrival handover for ANY self-haul truck: portal-assigned OR
walk-in registered at the gate (isSelfHaulBooking: assigned_at set, or no
EDR last-mile leg). Same rule now guards the exit paper.
- remind every 5 minutes (in-app + SMS + email) until the handover is signed
(@Cron in HandoverService; one reminder per booking per tick)
- Truck Leaving no longer opens blank: the import queue mapper now carries
inv.notes, so the saved arrival renders read-only with only gate-out time
and gross weight editable
- container bookings get "Weigh truck? Yes/No": No skips tare/gross and the
container weight match (weighingSkipped on ReleaseOrderDto, decision made at
arrival sticks for the exit via the Weighing: SKIPPED note). Bulk always
weighs, unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
READY_FOR_PICKUP allows STORED (park an import item back into storage), but
STORED allowed only RESERVED / READY_FOR_LOADING - so readyForPickup() hit
assertTransition(STORED, READY_FOR_PICKUP) and threw. The item could never
return to pickup, and getNextInventoryAction returned null for an import STORED
item, leaving the row with no action at all.
- allow STORED -> READY_FOR_PICKUP
- an inspected import STORED item now advances to ready-for-pickup
readyForPickup() still rejects non-IMPORT inventory, so the new edge cannot be
reached from the export flow.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Customer reviews the generated handover before signing:
- add booking-scoped handover-document endpoint (portal only has bookingId)
- ApproveDeliveryModal renders the handover PDF, then applies the customer's
saved signature on approve and returns the signed PDF
- ApproveDeliveryButton opens the modal instead of one-click silent signing
Handover generation + sign notification (in-app + SMS + email) and the
"Approve delivery" visibility on an awaiting-signature handover were committed
earlier; this wires the review-and-sign step.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a per-container/bulk items view for a booking with derived lifecycle
stage (PENDING -> RECEIVED -> GRN -> LOADED -> LEFT -> DELIVERED) and reference
badges (booking, contract, last-mile). Backend containerItems() aggregates
booking_container_units + customer_truck_containers + inventory; exposed at
GET warehouse-inventory/bookings/:id/container-items.
Frontend ContainerItemsModal (opened from the View Details eye): stage tabs
with counts, ref columns, checkbox multiselect of loadable items -> pick truck
-> load (Truck_dispatch), and per-row per-truck Exit Paper.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
