@burdenoff/microfe-movethewheels 2026.1031.1 → 2026.1031.2

package/src/movethewheels/hooks/useTracking.ts

@@ -13,6 +13,11 @@ import {
   useDrivers,
 } from './useFleet';
 import { mapOrder, type ApiOrder, useOrder } from './useOrders';
+import {
+  mapTrackingAlert,
+  sortTrackingAlerts,
+  type ApiTrackingAlert,
+} from '../utils/trackingAlerts';
 
 interface UseTrackingOptions {
   entityId?: string;
@@ -205,10 +210,27 @@ const ACTIVE_DELIVERIES_QUERY = `
 const TRACKING_ALERTS_QUERY = `
   query GetTrackingAlerts {
     trackingAlerts {
+      id
       shipmentId
       shipmentNumber
       alertType
       message
+      riskScore
+      promisedDelivery
+      predictedDelivery
+      signals
+      acknowledged
+      acknowledgedAt
+    }
+  }
+`;
+
+const ACKNOWLEDGE_TRACKING_ALERT_MUTATION = `
+  mutation AcknowledgeMtwTrackingAlert($shipmentId: ID!, $alertType: MtwTrackingAlertType!) {
+    acknowledgeMtwTrackingAlert(shipmentId: $shipmentId, alertType: $alertType) {
+      id
+      acknowledged
+      acknowledgedAt
     }
   }
 `;
@@ -631,24 +653,11 @@ export function useTrackingAlerts() {
     setIsLoading(true);
     setError(null);
     try {
-      const data = await executeGraphQL<{
-        trackingAlerts: Array<{
-          shipmentId: string;
-          shipmentNumber: string;
-          alertType: string;
-          message: string;
-        }>;
-      }>(graphQLOptions, TRACKING_ALERTS_QUERY);
-
-      setAlerts(
-        data.trackingAlerts.map((alert) => ({
-          id: `${alert.shipmentId}-${alert.alertType}`,
-          type: 'delay',
-          severity: 'medium',
-          message: `${alert.shipmentNumber}: ${alert.message}`,
-          acknowledged: false,
-        }))
+      const data = await executeGraphQL<{ trackingAlerts: ApiTrackingAlert[] }>(
+        graphQLOptions,
+        TRACKING_ALERTS_QUERY
       );
+      setAlerts(sortTrackingAlerts(data.trackingAlerts.map(mapTrackingAlert)));
     } catch (fetchError) {
       setError(
         fetchError instanceof Error ? fetchError : new Error('Failed to load tracking alerts')
@@ -664,11 +673,46 @@ export function useTrackingAlerts() {
 
   const unacknowledgedAlerts = useMemo(() => alerts.filter((item) => !item.acknowledged), [alerts]);
 
-  const acknowledgeAlert = useCallback(async (alertId: string): Promise<void> => {
-    setAlerts((previous) =>
-      previous.map((item) => (item.id === alertId ? { ...item, acknowledged: true } : item))
-    );
-  }, []);
+  /**
+   * Persist the acknowledgement server-side (BOFF-10397) so it survives a
+   * reload and is shared with the rest of the workspace. The alert is hidden
+   * optimistically and restored if the mutation fails.
+   */
+  const acknowledgeAlert = useCallback(
+    async (alertId: string): Promise<void> => {
+      const target = alerts.find((item) => item.id === alertId);
+      if (!target?.shipmentId || !target.kind) return;
+      setAlerts((previous) =>
+        previous.map((item) => (item.id === alertId ? { ...item, acknowledged: true } : item))
+      );
+      try {
+        const data = await executeGraphQL<{
+          acknowledgeMtwTrackingAlert: {
+            id: string;
+            acknowledged: boolean;
+            acknowledgedAt: string;
+          };
+        }>(
+          graphQLOptions,
+          ACKNOWLEDGE_TRACKING_ALERT_MUTATION,
+          // Idempotent upsert server-side, so transient retries are safe.
+          { shipmentId: target.shipmentId, alertType: target.kind }
+        );
+        const acknowledgedAt = new Date(data.acknowledgeMtwTrackingAlert.acknowledgedAt);
+        setAlerts((previous) =>
+          previous.map((item) =>
+            item.id === alertId ? { ...item, acknowledged: true, acknowledgedAt } : item
+          )
+        );
+      } catch (ackError) {
+        setAlerts((previous) =>
+          previous.map((item) => (item.id === alertId ? { ...item, acknowledged: false } : item))
+        );
+        throw ackError instanceof Error ? ackError : new Error('Failed to acknowledge alert');
+      }
+    },
+    [alerts, graphQLOptions]
+  );
 
   return {
     alerts,

package/src/movethewheels/pages/DashboardPage.tsx

@@ -21,6 +21,7 @@ import {
 import { PageLayout, PageSection } from '../components/PageLayout';
 import { MetricCard, MetricGrid, type MetricDelta } from '../components/MetricCard';
 import { StatusBadge } from '../components/StatusBadge';
+import { TrackingAlertList } from '../components/TrackingAlertList';
 import { LogisticsMap, type LogisticsMarker } from '../components/maps';
 import { VolumeBar } from '../components/charts';
 import { deliveryMarkerStatus, firstRealLatLng } from '../utils/mapMarkers';
@@ -67,7 +68,7 @@ export default function DashboardPage() {
   const { stats: orderStats } = useOrderStats();
   const { stats: fleetStats } = useFleetStats();
   const { activeDeliveries } = useLiveTracking();
-  const { unacknowledgedAlerts } = useTrackingAlerts();
+  const { unacknowledgedAlerts, acknowledgeAlert, refetch: refetchAlerts } = useTrackingAlerts();
 
   const orderSpark = useMemo(
     () => analytics.trends.dailyOrders.map((d) => d.orders),
@@ -265,25 +266,14 @@ export default function DashboardPage() {
             </CardHeader>
             <CardContent>
               {unacknowledgedAlerts.length > 0 ? (
-                <div className="space-y-3">
-                  {unacknowledgedAlerts.slice(0, 4).map((alert) => (
-                    <div
-                      key={alert.id}
-                      className={`rounded-lg p-3 text-sm ${
-                        alert.severity === 'critical' || alert.severity === 'high'
-                          ? 'bg-status-error-bg-subtle'
-                          : 'bg-status-warning-bg-subtle'
-                      }`}
-                    >
-                      <p className="font-medium">{alert.message}</p>
-                      <p className="mt-1 text-xs text-text-secondary">
-                        {alert.timestamp
-                          ? formatDate(alert.timestamp, 'relative')
-                          : 'Time not recorded'}
-                      </p>
-                    </div>
-                  ))}
-                </div>
+                <TrackingAlertList
+                  alerts={unacknowledgedAlerts}
+                  limit={4}
+                  t={t}
+                  onAcknowledge={acknowledgeAlert}
+                  onOpenOrder={(deliveryJobId) => goTo(`orders/${deliveryJobId}`)}
+                  onChanged={refetchAlerts}
+                />
               ) : (
                 <p className="py-4 text-center text-sm text-text-secondary">
                   {t(

package/src/movethewheels/pages/LiveTrackingPage.tsx

@@ -28,13 +28,20 @@ import { useLiveTracking, useTrackingAlerts } from '../hooks/useTracking';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { TrackingAlertList } from '../components/TrackingAlertList';
+import { useI18n } from '@burdenoff/fe-libs/shared/providers/shell/I18nProvider';
 
 type LiveFilter = 'all' | 'in_transit' | 'out_for_delivery' | 'other';
 
 export default function LiveTrackingPage() {
   const { basePath, navigate } = useMoveTheWheels();
   const { activeDeliveries, isLoading, refetch } = useLiveTracking();
-  const { unacknowledgedAlerts } = useTrackingAlerts();
+  const { t: translate } = useI18n();
+  const t = (key: string, fallback: string): string => {
+    const value = translate(key);
+    return value === key ? fallback : value;
+  };
+  const { unacknowledgedAlerts, acknowledgeAlert, refetch: refetchAlerts } = useTrackingAlerts();
   const [viewMode, setViewMode] = useState<'map' | 'list'>('map');
   const [selectedDelivery, setSelectedDelivery] = useState<string | null>(null);
   const [filter, setFilter] = useState<LiveFilter>('all');
@@ -420,7 +427,7 @@ export default function LiveTrackingPage() {
           <Card>
             <CardHeader>
               <CardTitle className="flex items-center gap-2">
-                Alerts
+                {t('movethewheels.tracking.live.alerts', 'Alerts')}
                 {unacknowledgedAlerts.length > 0 && (
                   <Badge variant="destructive">{unacknowledgedAlerts.length}</Badge>
                 )}
@@ -428,28 +435,19 @@ export default function LiveTrackingPage() {
             </CardHeader>
             <CardContent>
               {unacknowledgedAlerts.length > 0 ? (
-                <div className="space-y-3">
-                  {unacknowledgedAlerts.slice(0, 5).map((alert) => (
-                    <div
-                      key={alert.id}
-                      className={`p-3 rounded-lg text-sm ${
-                        alert.severity === 'critical' || alert.severity === 'high'
-                          ? 'bg-status-error-bg-subtle'
-                          : 'bg-status-warning-bg-subtle'
-                      }`}
-                    >
-                      <p className="font-medium">{alert.message}</p>
-                      <p className="text-xs text-text-secondary mt-1">
-                        {alert.timestamp
-                          ? formatDate(alert.timestamp, 'relative')
-                          : 'Time not recorded'}
-                      </p>
-                    </div>
-                  ))}
-                </div>
+                <TrackingAlertList
+                  alerts={unacknowledgedAlerts}
+                  limit={5}
+                  t={t}
+                  onAcknowledge={acknowledgeAlert}
+                  onOpenOrder={(deliveryJobId) => goTo(`orders/${deliveryJobId}`)}
+                  onChanged={refetchAlerts}
+                />
               ) : (
                 <div className="text-center text-text-secondary py-4">
-                  <p className="text-sm">No active alerts</p>
+                  <p className="text-sm">
+                    {t('movethewheels.tracking.live.noAlerts', 'No active alerts')}
+                  </p>
                 </div>
               )}
             </CardContent>

package/src/movethewheels/types/index.ts

@@ -513,14 +513,29 @@ export interface Route {
 }
 
 // Tracking alert type
+export type TrackingAlertSeverity = 'low' | 'medium' | 'high' | 'critical';
+
 export interface TrackingAlert {
   id: string;
   type: 'delay' | 'deviation' | 'temperature' | 'damage' | 'security';
-  severity: 'low' | 'medium' | 'high' | 'critical';
+  severity: TrackingAlertSeverity;
   message: string;
   timestamp?: Date;
   acknowledged: boolean;
   resolvedAt?: Date;
+  /** Server alert kind for shipment alerts (BOFF-10397). */
+  kind?: 'DELAYED' | 'AT_RISK';
+  shipmentId?: string;
+  shipmentNumber?: string;
+  /** 0–100 forecast risk score; AT_RISK alerts only. */
+  riskScore?: number;
+  /** The shipment's promised delivery the alert was raised against. */
+  promisedDelivery?: Date;
+  /** Earliest forecast delivery time; AT_RISK alerts only. */
+  predictedDelivery?: Date;
+  /** Contributing risk signal codes; AT_RISK alerts only. */
+  signals?: string[];
+  acknowledgedAt?: Date;
 }
 
 // Tracking type

package/src/movethewheels/utils/trackingAlerts.ts

@@ -0,0 +1,151 @@
+/**
+ * Tracking alert mapping (BOFF-10397).
+ *
+ * `trackingAlerts` returns two kinds of alert: `DELAYED` once a shipment's
+ * promised delivery has passed, and the predictive `AT_RISK` alert raised
+ * while the promise is still ahead but the deterministic forecast says it
+ * will be missed. These helpers turn the API rows into the UI model: a
+ * severity, the predicted window and the contributing signals.
+ */
+
+import type { TrackingAlert, TrackingAlertSeverity } from '../types';
+
+export type RiskSignalCode =
+  | 'LEG_SLIP'
+  | 'OPEN_LEG_OVERDUE'
+  | 'ROUTE_DURATION_OVERRUN'
+  | 'EXCESS_DWELL'
+  | 'TRACKING_STALE'
+  | 'VEHICLE_UNAVAILABLE'
+  | 'CARRIER_LATE_HISTORY';
+
+export type TrackingAlertKind = 'DELAYED' | 'AT_RISK';
+
+export interface ApiTrackingAlert {
+  id: string;
+  shipmentId: string;
+  shipmentNumber: string;
+  alertType: string;
+  message: string;
+  riskScore?: number | null;
+  promisedDelivery?: string | null;
+  predictedDelivery?: string | null;
+  signals?: RiskSignalCode[] | null;
+  acknowledged: boolean;
+  acknowledgedAt?: string | null;
+}
+
+/** Risk score at or above which an AT_RISK alert is shown as high severity (matches the backend HIGH level). */
+export const HIGH_RISK_SCORE = 70;
+
+/**
+ * DELAYED is always high: the promise is already broken. AT_RISK follows the
+ * forecast's risk score; the backend only raises AT_RISK at MEDIUM or above,
+ * so anything below the HIGH band is medium.
+ */
+export function trackingAlertSeverity(
+  alertType: string,
+  riskScore: number | null | undefined
+): TrackingAlertSeverity {
+  if (alertType === 'DELAYED') return 'high';
+  if (alertType === 'AT_RISK') {
+    return typeof riskScore === 'number' && riskScore >= HIGH_RISK_SCORE ? 'high' : 'medium';
+  }
+  return 'medium';
+}
+
+const toDate = (value: string | null | undefined): Date | undefined => {
+  if (!value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
+export function mapTrackingAlert(alert: ApiTrackingAlert): TrackingAlert {
+  const kind: TrackingAlertKind = alert.alertType === 'AT_RISK' ? 'AT_RISK' : 'DELAYED';
+  return {
+    id: alert.id,
+    type: 'delay',
+    kind,
+    severity: trackingAlertSeverity(alert.alertType, alert.riskScore),
+    message: alert.message,
+    shipmentId: alert.shipmentId,
+    shipmentNumber: alert.shipmentNumber,
+    riskScore: alert.riskScore ?? undefined,
+    promisedDelivery: toDate(alert.promisedDelivery),
+    predictedDelivery: toDate(alert.predictedDelivery),
+    signals: alert.signals ?? [],
+    acknowledged: alert.acknowledged,
+    acknowledgedAt: toDate(alert.acknowledgedAt),
+  };
+}
+
+/** Highest severity first, then highest risk score; stable otherwise. */
+const SEVERITY_RANK: Record<TrackingAlertSeverity, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+export function sortTrackingAlerts(alerts: TrackingAlert[]): TrackingAlert[] {
+  return [...alerts].sort(
+    (a, b) =>
+      SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+      (b.riskScore ?? -1) - (a.riskScore ?? -1)
+  );
+}
+
+/** Translation key + English fallback for each risk signal code. */
+export const RISK_SIGNAL_LABELS: Record<RiskSignalCode, { key: string; fallback: string }> = {
+  LEG_SLIP: { key: 'movethewheels.risk.signals.legSlip', fallback: 'Leg running late' },
+  OPEN_LEG_OVERDUE: { key: 'movethewheels.risk.signals.openLegOverdue', fallback: 'Leg overdue' },
+  ROUTE_DURATION_OVERRUN: {
+    key: 'movethewheels.risk.signals.routeOverrun',
+    fallback: 'Route taking longer than planned',
+  },
+  EXCESS_DWELL: { key: 'movethewheels.risk.signals.excessDwell', fallback: 'Long stop' },
+  TRACKING_STALE: {
+    key: 'movethewheels.risk.signals.trackingStale',
+    fallback: 'No recent tracking',
+  },
+  VEHICLE_UNAVAILABLE: {
+    key: 'movethewheels.risk.signals.vehicleUnavailable',
+    fallback: 'Vehicle unavailable',
+  },
+  CARRIER_LATE_HISTORY: {
+    key: 'movethewheels.risk.signals.carrierLateHistory',
+    fallback: 'Carrier often late',
+  },
+};
+
+export function riskSignalLabel(
+  code: string,
+  t: (key: string, fallback: string) => string
+): string {
+  const label = RISK_SIGNAL_LABELS[code as RiskSignalCode];
+  return label ? t(label.key, label.fallback) : code;
+}
+
+/** Minutes between the promise and the predicted delivery, or null when unknown / not late. */
+export function predictedSlipMinutes(
+  alert: Pick<TrackingAlert, 'promisedDelivery' | 'predictedDelivery'>
+): number | null {
+  if (!alert.promisedDelivery || !alert.predictedDelivery) return null;
+  const minutes = Math.round(
+    (alert.predictedDelivery.getTime() - alert.promisedDelivery.getTime()) / 60_000
+  );
+  return minutes > 0 ? minutes : null;
+}
+
+/** "45 min", "3 h 20 min", "2 d 4 h" — compact duration for alert cards. */
+export function formatSlip(minutes: number): string {
+  if (minutes < 60) return `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    const rest = minutes % 60;
+    return rest > 0 ? `${hours} h ${rest} min` : `${hours} h`;
+  }
+  const days = Math.floor(hours / 24);
+  const restHours = hours % 24;
+  return restHours > 0 ? `${days} d ${restHours} h` : `${days} d`;
+}