@burdenoff/microfe-movethewheels 2026.1031.1 → 2026.1031.3

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -23,6 +23,7 @@ import {
   DollarSign,
   Bot,
   Store,
+  ArrowDownUp,
 } from 'lucide-react';
 import { MoveTheWheelsProvider } from './providers/MoveTheWheelsProvider';
 import { FeatureFlagProvider } from '@burdenoff/fe-libs/shared/feature-flags';
@@ -241,6 +242,13 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           icon: <Store size={16} />,
           order: 6,
         },
+        {
+          id: 'mtw-import-export',
+          label: tr('movethewheels.root.nav.importExport', 'Import / Export'),
+          path: joinPath(basePath, 'import-export'),
+          icon: <ArrowDownUp size={16} />,
+          order: 6,
+        },
         {
           id: 'mtw-routes',
           label: tr('movethewheels.root.nav.routes', 'Routes'),

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -72,6 +72,7 @@ const WarehouseDetailsPage = lazy(() => import('./pages/WarehouseDetailsPage'));
 const CustomersPage = lazy(() => import('./pages/CustomersPage'));
 const CustomerDetailsPage = lazy(() => import('./pages/CustomerDetailsPage'));
 const MarketplacePage = lazy(() => import('./pages/MarketplacePage'));
+const ImportExportPage = lazy(() => import('./pages/ImportExportPage'));
 const RoutesPage = lazy(() => import('./pages/RoutesPage'));
 const RouteDetailsPage = lazy(() => import('./pages/RouteDetailsPage'));
 const AnalyticsPage = lazy(() => import('./pages/AnalyticsPage'));
@@ -160,6 +161,9 @@ export function MoveTheWheelsRoutes() {
         {/* Marketplace — service providers and offerings (BOFF-3988) */}
         <Route path="marketplace" element={<MarketplacePage />} />
 
+        {/* Bulk CSV/JSON import and dataset export (BOFF-3990) */}
+        <Route path="import-export" element={<ImportExportPage />} />
+
         {/* Routes */}
         <Route path="routes" element={<RoutesPage />} />
         <Route path="routes/trip-utilization" element={<TripUtilizationPage />} />

package/src/movethewheels/components/ShipmentRiskDialog.tsx

@@ -0,0 +1,315 @@
+/**
+ * ShipmentRiskDialog (BOFF-10397)
+ *
+ * The risk panel for one shipment, backed by `mtwShipmentRiskForecast`: risk
+ * score and level, promised vs predicted delivery window, the contributing
+ * signals with their weights, and the recommended action wired to the
+ * mutation the forecast names.
+ */
+
+import { useEffect, useState } from 'react';
+
+import {
+  Badge,
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  Skeleton,
+  Textarea,
+} from './ui';
+import {
+  useShipmentRisk,
+  type RiskLevel,
+  type RiskRecommendedAction,
+} from '../hooks/useShipmentRisk';
+import { formatDateTime } from '../utils/formatters';
+import { formatSlip, riskSignalLabel } from '../utils/trackingAlerts';
+
+type Translate = (key: string, fallback: string) => string;
+
+interface ShipmentRiskDialogProps {
+  shipmentId: string | undefined;
+  shipmentNumber: string | undefined;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  t: Translate;
+  onOpenOrder: (deliveryJobId: string) => void;
+  onChanged: () => void;
+}
+
+const LEVEL_LABELS: Record<RiskLevel, { key: string; fallback: string }> = {
+  NONE: { key: 'movethewheels.risk.level.none', fallback: 'No risk' },
+  LOW: { key: 'movethewheels.risk.level.low', fallback: 'Low' },
+  MEDIUM: { key: 'movethewheels.risk.level.medium', fallback: 'Medium' },
+  HIGH: { key: 'movethewheels.risk.level.high', fallback: 'High' },
+};
+
+const ACTION_LABELS: Record<RiskRecommendedAction, { key: string; fallback: string }> = {
+  NONE: { key: 'movethewheels.risk.action.none', fallback: 'No action needed' },
+  MONITOR: { key: 'movethewheels.risk.action.monitor', fallback: 'Keep monitoring this shipment' },
+  REPROMISE_DELIVERY: {
+    key: 'movethewheels.risk.action.repromise',
+    fallback: 'Re-promise the delivery to the predicted time',
+  },
+  REQUEST_TRACKING_UPDATE: {
+    key: 'movethewheels.risk.action.trackingUpdate',
+    fallback: 'Get a tracking update from the driver or carrier',
+  },
+  REASSIGN_VEHICLE: {
+    key: 'movethewheels.risk.action.reassign',
+    fallback: 'Reassign the vehicle on this order',
+  },
+};
+
+function describeSignal(
+  signal: { minutes: number | null; ratio: number | null },
+  t: Translate
+): string | null {
+  if (signal.ratio !== null) {
+    return `${Math.round(signal.ratio * 100)}% ${t('movethewheels.risk.lateRate', 'late recently')}`;
+  }
+  if (signal.minutes !== null && signal.minutes > 0) return formatSlip(signal.minutes);
+  return null;
+}
+
+export function ShipmentRiskDialog({
+  shipmentId,
+  shipmentNumber,
+  open,
+  onOpenChange,
+  t,
+  onOpenOrder,
+  onChanged,
+}: ShipmentRiskDialogProps) {
+  const { forecast, shipment, isLoading, error, refetch, repromise, recordTrackingUpdate } =
+    useShipmentRisk(open ? shipmentId : undefined);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [actionDone, setActionDone] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [details, setDetails] = useState('');
+
+  useEffect(() => {
+    setActionError(null);
+    setActionDone(null);
+    setDetails('');
+  }, [shipmentId, open]);
+
+  const run = async (work: () => Promise<void>, done: string) => {
+    setBusy(true);
+    setActionError(null);
+    setActionDone(null);
+    try {
+      await work();
+      setActionDone(done);
+      onChanged();
+    } catch (failure) {
+      setActionError(
+        failure instanceof Error
+          ? failure.message
+          : t('movethewheels.risk.actionFailed', 'The action failed')
+      );
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const repromiseTo = forecast?.predictedDeliveryLatest ?? forecast?.predictedDeliveryEarliest;
+  const reassignJobId = shipment?.deliveryJobId ?? null;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-lg">
+        <DialogHeader>
+          <DialogTitle>
+            {t('movethewheels.risk.title', 'Delivery risk')}
+            {shipmentNumber ? ` · ${shipmentNumber}` : ''}
+          </DialogTitle>
+          <DialogDescription>
+            {t(
+              'movethewheels.risk.description',
+              'Forecast from this shipment’s legs, route, tracking, vehicle and carrier history.'
+            )}
+          </DialogDescription>
+        </DialogHeader>
+
+        {isLoading && !forecast && (
+          <div className="space-y-2" aria-busy="true">
+            <Skeleton className="h-6 w-1/2" />
+            <Skeleton className="h-16 w-full" />
+          </div>
+        )}
+
+        {error && !isLoading && (
+          <div role="alert" className="space-y-2 text-sm">
+            <p className="text-status-error-text">{error.message}</p>
+            <Button size="sm" variant="outline" onClick={refetch}>
+              {t('movethewheels.risk.retry', 'Retry')}
+            </Button>
+          </div>
+        )}
+
+        {forecast && (
+          <div className="space-y-4 text-sm" data-testid="shipment-risk-panel">
+            <div className="flex flex-wrap items-center gap-2">
+              <Badge variant={forecast.riskLevel === 'HIGH' ? 'destructive' : 'secondary'}>
+                {t(LEVEL_LABELS[forecast.riskLevel].key, LEVEL_LABELS[forecast.riskLevel].fallback)}
+              </Badge>
+              <span className="text-text-secondary">
+                {t('movethewheels.risk.score', 'Risk score')}:{' '}
+                <span className="font-medium text-text-primary">{forecast.riskScore}/100</span>
+              </span>
+              {forecast.breached && (
+                <Badge variant="destructive">
+                  {t('movethewheels.risk.breached', 'Promise missed')}
+                </Badge>
+              )}
+            </div>
+
+            <dl className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+              <div>
+                <dt className="text-xs text-text-secondary">
+                  {t('movethewheels.alerts.promised', 'Promised')}
+                </dt>
+                <dd>
+                  {forecast.promisedDelivery
+                    ? formatDateTime(forecast.promisedDelivery)
+                    : t('movethewheels.risk.noPromise', 'No promised time')}
+                </dd>
+              </div>
+              <div>
+                <dt className="text-xs text-text-secondary">
+                  {t('movethewheels.risk.window', 'Predicted window')}
+                </dt>
+                <dd>
+                  {forecast.predictedDeliveryEarliest
+                    ? `${formatDateTime(forecast.predictedDeliveryEarliest)}${
+                        forecast.predictedDeliveryLatest &&
+                        forecast.predictedDeliveryLatest !== forecast.predictedDeliveryEarliest
+                          ? ` – ${formatDateTime(forecast.predictedDeliveryLatest)}`
+                          : ''
+                      }`
+                    : t('movethewheels.risk.noPrediction', 'Not enough data to predict')}
+                  {forecast.predictedSlipMinutes > 0 && (
+                    <span className="ml-1 text-status-error-text">
+                      (+{formatSlip(forecast.predictedSlipMinutes)})
+                    </span>
+                  )}
+                </dd>
+              </div>
+            </dl>
+
+            <div>
+              <p className="mb-1 text-xs text-text-secondary">
+                {t('movethewheels.alerts.signals', 'Risk signals')}
+              </p>
+              {forecast.signals.length > 0 ? (
+                <ul className="space-y-1">
+                  {forecast.signals.map((signal) => {
+                    const detail = describeSignal(signal, t);
+                    return (
+                      <li
+                        key={signal.code}
+                        className="flex items-center justify-between rounded border border-border-primary px-2 py-1"
+                      >
+                        <span>
+                          {riskSignalLabel(signal.code, t)}
+                          {detail && <span className="ml-1 text-text-secondary">· {detail}</span>}
+                        </span>
+                        <span className="text-xs text-text-secondary">+{signal.weight}</span>
+                      </li>
+                    );
+                  })}
+                </ul>
+              ) : (
+                <p className="text-text-secondary">
+                  {t('movethewheels.risk.noSignals', 'No risk signals right now')}
+                </p>
+              )}
+            </div>
+
+            <div className="rounded-lg bg-status-info-bg-subtle p-3">
+              <p className="text-xs text-text-secondary">
+                {t('movethewheels.risk.recommended', 'Recommended action')}
+              </p>
+              <p className="font-medium">
+                {t(
+                  ACTION_LABELS[forecast.recommendedAction].key,
+                  ACTION_LABELS[forecast.recommendedAction].fallback
+                )}
+              </p>
+
+              {forecast.recommendedAction === 'REPROMISE_DELIVERY' && repromiseTo && (
+                <Button
+                  size="sm"
+                  className="mt-2"
+                  disabled={busy}
+                  onClick={() =>
+                    void run(
+                      () => repromise(repromiseTo),
+                      t('movethewheels.risk.repromised', 'Delivery re-promised')
+                    )
+                  }
+                >
+                  {t('movethewheels.risk.repromiseTo', 'Re-promise to')}{' '}
+                  {formatDateTime(repromiseTo)}
+                </Button>
+              )}
+
+              {forecast.recommendedAction === 'REQUEST_TRACKING_UPDATE' && (
+                <div className="mt-2 space-y-2">
+                  <Textarea
+                    value={details}
+                    onChange={(event) => setDetails(event.target.value)}
+                    maxLength={500}
+                    aria-label={t('movethewheels.risk.updateDetails', 'Tracking update')}
+                    placeholder={t(
+                      'movethewheels.risk.updatePlaceholder',
+                      'What did the driver or carrier report?'
+                    )}
+                  />
+                  <Button
+                    size="sm"
+                    disabled={busy || details.trim().length === 0}
+                    onClick={() =>
+                      void run(
+                        () => recordTrackingUpdate(details.trim()),
+                        t('movethewheels.risk.updateRecorded', 'Tracking update recorded')
+                      )
+                    }
+                  >
+                    {t('movethewheels.risk.recordUpdate', 'Record tracking update')}
+                  </Button>
+                </div>
+              )}
+
+              {forecast.recommendedAction === 'REASSIGN_VEHICLE' && reassignJobId && (
+                <Button size="sm" className="mt-2" onClick={() => onOpenOrder(reassignJobId)}>
+                  {t('movethewheels.risk.openOrder', 'Open order to reassign')}
+                </Button>
+              )}
+
+              {actionDone && (
+                <p role="status" className="mt-2 text-xs text-status-success-text">
+                  {actionDone}
+                </p>
+              )}
+              {actionError && (
+                <p role="alert" className="mt-2 text-xs text-status-error-text">
+                  {actionError}
+                </p>
+              )}
+            </div>
+
+            <p className="text-xs text-text-secondary">
+              {t('movethewheels.risk.evaluated', 'Evaluated')}{' '}
+              {formatDateTime(forecast.evaluatedAt)}
+            </p>
+          </div>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/movethewheels/components/TrackingAlertList.tsx

@@ -0,0 +1,188 @@
+/**
+ * TrackingAlertList (BOFF-10397)
+ *
+ * Shipment exception alerts for the Dashboard and Live Tracking pages. Each
+ * card shows the alert's severity, the promised vs predicted delivery, the
+ * contributing risk signals, and lets the operator acknowledge it (persisted
+ * server-side) or open the shipment's risk forecast.
+ */
+
+import { useState } from 'react';
+import { CheckCircle2, Clock, Gauge } from 'lucide-react';
+
+import { Badge, Button } from './ui';
+import { ShipmentRiskDialog } from './ShipmentRiskDialog';
+import type { TrackingAlert } from '../types';
+import { formatDateTime } from '../utils/formatters';
+import { formatSlip, predictedSlipMinutes, riskSignalLabel } from '../utils/trackingAlerts';
+
+type Translate = (key: string, fallback: string) => string;
+
+interface TrackingAlertListProps {
+  alerts: TrackingAlert[];
+  limit: number;
+  t: Translate;
+  onAcknowledge: (alertId: string) => Promise<void>;
+  /** Opens the order (delivery job) page, where a vehicle can be reassigned. */
+  onOpenOrder: (deliveryJobId: string) => void;
+  /** Called after a risk action changed the shipment, so callers can reload alerts. */
+  onChanged: () => void;
+}
+
+const SEVERITY_STYLES: Record<TrackingAlert['severity'], string> = {
+  critical: 'bg-status-error-bg-subtle border-status-error-border',
+  high: 'bg-status-error-bg-subtle border-status-error-border',
+  medium: 'bg-status-warning-bg-subtle border-status-warning-border',
+  low: 'bg-surface-secondary border-border-primary',
+};
+
+function SeverityBadge({ alert, t }: { alert: TrackingAlert; t: Translate }) {
+  const high = alert.severity === 'high' || alert.severity === 'critical';
+  const label =
+    alert.kind === 'AT_RISK'
+      ? t('movethewheels.alerts.kind.atRisk', 'At risk')
+      : t('movethewheels.alerts.kind.delayed', 'Delayed');
+  return (
+    <Badge variant={high ? 'destructive' : 'secondary'} className="shrink-0">
+      {label}
+      {alert.kind === 'AT_RISK' && typeof alert.riskScore === 'number'
+        ? ` · ${alert.riskScore}`
+        : ''}
+    </Badge>
+  );
+}
+
+function DeliveryWindow({ alert, t }: { alert: TrackingAlert; t: Translate }) {
+  const slip = predictedSlipMinutes(alert);
+  if (!alert.promisedDelivery && !alert.predictedDelivery) return null;
+  return (
+    <dl className="mt-2 grid grid-cols-1 gap-x-4 gap-y-1 text-xs text-text-secondary sm:grid-cols-2">
+      {alert.promisedDelivery && (
+        <div className="flex items-center gap-1">
+          <Clock size={12} aria-hidden="true" />
+          <dt>{t('movethewheels.alerts.promised', 'Promised')}:</dt>
+          <dd className="text-text-primary">{formatDateTime(alert.promisedDelivery)}</dd>
+        </div>
+      )}
+      {alert.predictedDelivery && (
+        <div className="flex items-center gap-1">
+          <Gauge size={12} aria-hidden="true" />
+          <dt>{t('movethewheels.alerts.predicted', 'Predicted')}:</dt>
+          <dd className="text-text-primary">
+            {formatDateTime(alert.predictedDelivery)}
+            {slip !== null && (
+              <span className="ml-1 text-status-error-text">(+{formatSlip(slip)})</span>
+            )}
+          </dd>
+        </div>
+      )}
+    </dl>
+  );
+}
+
+export function TrackingAlertList({
+  alerts,
+  limit,
+  t,
+  onAcknowledge,
+  onOpenOrder,
+  onChanged,
+}: TrackingAlertListProps) {
+  const [pendingId, setPendingId] = useState<string | null>(null);
+  const [ackError, setAckError] = useState<string | null>(null);
+  const [riskAlert, setRiskAlert] = useState<TrackingAlert | null>(null);
+
+  const acknowledge = async (alertId: string) => {
+    setPendingId(alertId);
+    setAckError(null);
+    try {
+      await onAcknowledge(alertId);
+    } catch (error) {
+      setAckError(
+        error instanceof Error
+          ? error.message
+          : t('movethewheels.alerts.ackFailed', 'Could not acknowledge the alert')
+      );
+    } finally {
+      setPendingId(null);
+    }
+  };
+
+  return (
+    <>
+      {ackError && (
+        <p role="alert" className="mb-2 text-xs text-status-error-text">
+          {ackError}
+        </p>
+      )}
+      <ul className="space-y-3" aria-label={t('movethewheels.alerts.listLabel', 'Shipment alerts')}>
+        {alerts.slice(0, limit).map((alert) => (
+          <li
+            key={alert.id}
+            data-testid="tracking-alert"
+            data-alert-kind={alert.kind}
+            className={`rounded-lg border p-3 text-sm ${SEVERITY_STYLES[alert.severity]}`}
+          >
+            <div className="flex items-start justify-between gap-2">
+              <p className="font-medium">
+                {alert.shipmentNumber ? `${alert.shipmentNumber}: ` : ''}
+                {alert.message}
+              </p>
+              <SeverityBadge alert={alert} t={t} />
+            </div>
+            <DeliveryWindow alert={alert} t={t} />
+            {alert.signals && alert.signals.length > 0 && (
+              <ul
+                className="mt-2 flex flex-wrap gap-1"
+                aria-label={t('movethewheels.alerts.signals', 'Risk signals')}
+              >
+                {alert.signals.map((code) => (
+                  <li
+                    key={code}
+                    className="rounded-full border border-border-primary bg-surface-primary px-2 py-0.5 text-xs text-text-secondary"
+                  >
+                    {riskSignalLabel(code, t)}
+                  </li>
+                ))}
+              </ul>
+            )}
+            <div className="mt-3 flex flex-wrap gap-2">
+              {alert.shipmentId && (
+                <Button size="sm" variant="outline" onClick={() => setRiskAlert(alert)}>
+                  {t('movethewheels.alerts.viewRisk', 'View risk')}
+                </Button>
+              )}
+              {alert.shipmentId && alert.kind && (
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  disabled={pendingId === alert.id}
+                  onClick={() => void acknowledge(alert.id)}
+                >
+                  <CheckCircle2 size={14} aria-hidden="true" />
+                  {pendingId === alert.id
+                    ? t('movethewheels.alerts.acknowledging', 'Acknowledging…')
+                    : t('movethewheels.alerts.acknowledge', 'Acknowledge')}
+                </Button>
+              )}
+            </div>
+          </li>
+        ))}
+      </ul>
+      <ShipmentRiskDialog
+        shipmentId={riskAlert?.shipmentId}
+        shipmentNumber={riskAlert?.shipmentNumber}
+        open={riskAlert !== null}
+        onOpenChange={(open) => {
+          if (!open) setRiskAlert(null);
+        }}
+        t={t}
+        onOpenOrder={(deliveryJobId) => {
+          setRiskAlert(null);
+          onOpenOrder(deliveryJobId);
+        }}
+        onChanged={onChanged}
+      />
+    </>
+  );
+}

package/src/movethewheels/hooks/useEntityImport.ts

@@ -0,0 +1,108 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+import {
+  MTW_IMPORT_MAX_BYTES,
+  MTW_IMPORT_SPEC_QUERY,
+  importEntity,
+  importMutation,
+  type MtwImportEntitySpec,
+  type MtwImportEntityType,
+  type MtwImportFormat,
+  type MtwImportResult,
+} from '../utils/entityImport';
+
+function useGraphQLOptions() {
+  const { apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser } =
+    useMoveTheWheels();
+  return useMemo(
+    () => ({
+      apiGatewayUrl,
+      authToken,
+      workspaceToken,
+      workspaceId,
+      tenantId,
+      actorId: currentUser?.id,
+    }),
+    [apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, currentUser?.id]
+  );
+}
+
+/** Column specification for every importable entity. */
+export function useImportSpec() {
+  const graphQLOptions = useGraphQLOptions();
+  const [specs, setSpecs] = useState<MtwImportEntitySpec[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!graphQLOptions.workspaceId) return;
+    let cancelled = false;
+    setIsLoading(true);
+    executeGraphQL<{ mtwImportSpec: MtwImportEntitySpec[] }>(graphQLOptions, MTW_IMPORT_SPEC_QUERY)
+      .then((data) => {
+        if (cancelled) return;
+        setSpecs(data.mtwImportSpec);
+        setError(null);
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled)
+          setError(caught instanceof Error ? caught : new Error('Could not load import columns'));
+      })
+      .finally(() => {
+        if (!cancelled) setIsLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [graphQLOptions]);
+
+  return { specs, isLoading, error };
+}
+
+export interface ImportRequest {
+  entityType: MtwImportEntityType;
+  format: MtwImportFormat;
+  content: string;
+  dryRun: boolean;
+  allowPartial: boolean;
+}
+
+/** Runs a validation or an import. Writes are sent once: a retry could create rows twice. */
+export function useEntityImport() {
+  const graphQLOptions = useGraphQLOptions();
+  const [isRunning, setIsRunning] = useState(false);
+
+  const run = useCallback(
+    async (request: ImportRequest): Promise<MtwImportResult> => {
+      if (new Blob([request.content]).size > MTW_IMPORT_MAX_BYTES) {
+        throw new Error('The file is larger than 2 MB. Split it into smaller files.');
+      }
+      const { field } = importEntity(request.entityType);
+      setIsRunning(true);
+      try {
+        const data = await executeGraphQL<Record<string, MtwImportResult>>(
+          graphQLOptions,
+          importMutation(request.entityType),
+          {
+            input: {
+              format: request.format,
+              content: request.content,
+              dryRun: request.dryRun,
+              allowPartial: request.allowPartial,
+            },
+          },
+          request.dryRun ? 'RETRY_TRANSIENT' : 'SINGLE_ATTEMPT'
+        );
+        const result = data[field];
+        if (!result) throw new Error('The import returned no result');
+        return result;
+      } finally {
+        setIsRunning(false);
+      }
+    },
+    [graphQLOptions]
+  );
+
+  return { run, isRunning };
+}