Prod migrate — Dispatch v1.5

Dispatch Station v1.5 — prod database apply

Apply after the app deploy that includes /dispatch and api/dispatch/*.

This runbook covers only the OMS Dispatch Station feature. It does not include BCMA compliance migrations (20260620003000, 20260620004200, 20260620004400) — ship those on their own release track.

Prod status (June 2026)

Checked with node scripts/db/check-dispatch-prod-schema.mjs:

Object	Prod today	After migrate
`oms_dispatch_trips`	missing	created
`oms_dispatch_trip_picklists`	missing	created
`tenant_rider_warehouses`	missing	created
`tenant_riders.identify_hash`	missing	created + backfilled
`oms_dispatch_trips.end_notes`	missing	created
`pick_lists.actual_delivery_date`	`date`	`timestamptz`
`pick_lists.assigned_tenant_rider_id`	never existed on prod	n/a — no drop migration

Removed from repo (do not apply)

Migration	Why
`20260619190000_drop_pick_lists_assigned_tenant_rider`	Deleted. Column was never added on prod; redundant drop only applied on dev during iteration.

Migrations to apply on prod (exactly 6)

Run in this order (timestamp order matches dependency chain):

#	Version	Purpose
1	`20260619120000_oms_dispatch_flow`	Trip tables, rider `identify_hash`, RLS, dispatch permissions
2	`20260619130000_tenant_rider_warehouses`	Rider ↔ warehouse access for rack board
3	`20260619140000_oms_dispatch_navigation`	Sidebar: Dispatch + Live Dispatch Board nav items
4	`20260619150000_tenant_riders_identify_hash_update`	Backfill hash on UPDATE; ensure all riders have badge QR hash
5	`20260619180000_oms_dispatch_trips_end_notes`	Optional runner note when closing trip at warehouse
6	`20260620130000_pick_lists_actual_delivery_datetime`	Store exact delivery time (trip end / staff receive)

Apply command

Preview pending (prod):

npm run db:status:prod

Apply dispatch-only batch:

CONFIRM_PROD_MIGRATE=yes node scripts/db/apply-selected-migrations.mjs --prod \
  20260619120000_oms_dispatch_flow \
  20260619130000_tenant_rider_warehouses \
  20260619140000_oms_dispatch_navigation \
  20260619150000_tenant_riders_identify_hash_update \
  20260619180000_oms_dispatch_trips_end_notes \
  20260620130000_pick_lists_actual_delivery_datetime

Verify schema:

node scripts/db/check-dispatch-prod-schema.mjs

Expected after success:

oms_dispatch_trips → table exists
tenant_rider_warehouses → table exists
tenant_riders_identify_hash → true
oms_dispatch_trips_end_notes → true
actual_delivery_date_type → timestamp with time zone

Post-migrate setup (tenant ops)

Riders — ensure each delivery rider has a row in tenant_riders; identify_hash is auto-generated (print badge QR: ailaaj:rider:<hash>).
Warehouse access — assign warehouses per rider in tenant_rider_warehouses so the rack board only shows their IPD racks.
Warehouse return QR — print wall QR per warehouse: ailaaj:wh:<warehouse_uuid> for trip end scan.
Permissions — staff need order.manage_shipments (or picklist view) for /dispatch nav; reports permission for Live Dispatch Board.

Smoke test

Open /dispatch (public kiosk or logged-in Sell → Dispatch).
Scan rider badge → claim screen shows rack with Ref# (source reference) on tiles.
Claim 1+ packed picklists → Start trip → thermal trip sheet prints with Ref# per demand.
Re-scan rider → re-entry guard → scan warehouse QR → picklists marked delivered with ward handoff + timestamp.

Not in this batch

These appear in npm run db:status:prod but are BCMA / reports, not Dispatch Station:

20260620003000_add_bcma_compliance_picklists
20260620004200_bcma_compliance_exclude_cancelled
20260620004400_bcma_compliance_exclude_refunded_transactions

Apply separately when that release ships.