@burdenoff/microfe-movethewheels 2026.830.4 → 2026.918.1

package/src/movethewheels/hooks/useFleetIntelligence.ts

@@ -0,0 +1,226 @@
+/**
+ * Fleet intelligence hooks — compliance/maintenance alerts, dispatch
+ * suggestions for a route, and logging a completed vehicle service.
+ *
+ * All three sit on top of wspace-movethewheels-svc's fleet module; the ranking
+ * and alert rules live server-side so every surface (web, CLI, MCP) agrees.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export type FleetAlertType =
+  | 'LICENSE_EXPIRED'
+  | 'LICENSE_EXPIRING'
+  | 'MAINTENANCE_OVERDUE'
+  | 'MAINTENANCE_DUE_SOON';
+export type FleetAlertSeverity = 'CRITICAL' | 'WARNING';
+export type FleetAlertSubjectType = 'VEHICLE' | 'DRIVER';
+
+export interface FleetAlert {
+  id: string;
+  type: FleetAlertType;
+  severity: FleetAlertSeverity;
+  subjectType: FleetAlertSubjectType;
+  subjectId: string;
+  subjectName: string;
+  message: string;
+  dueDate: string | null;
+  daysUntilDue: number | null;
+  kmUntilDue: number | null;
+}
+
+export interface VehicleSuggestion {
+  score: number;
+  reasons: string[];
+  vehicle: { id: string; vehicleNumber: string; make: string | null; model: string | null };
+}
+
+export interface DriverSuggestion {
+  score: number;
+  reasons: string[];
+  driver: { id: string; firstName: string; lastName: string; rating: number | null };
+}
+
+export interface AssignmentSuggestions {
+  routeId: string;
+  vehicles: VehicleSuggestion[];
+  drivers: DriverSuggestion[];
+}
+
+export interface RecordVehicleServiceInput {
+  /** ISO date-time. Defaults to now on the server. */
+  serviceDate?: string;
+  mileage?: number;
+  intervalDays?: number;
+  intervalKm?: number;
+}
+
+const FLEET_ALERTS_QUERY = `
+  query FleetAlerts {
+    fleetAlerts {
+      id
+      type
+      severity
+      subjectType
+      subjectId
+      subjectName
+      message
+      dueDate
+      daysUntilDue
+      kmUntilDue
+    }
+  }
+`;
+
+const ASSIGNMENT_SUGGESTIONS_QUERY = `
+  query AssignmentSuggestions($routeId: ID!, $limit: Int) {
+    assignmentSuggestions(routeId: $routeId, limit: $limit) {
+      routeId
+      vehicles {
+        score
+        reasons
+        vehicle {
+          id
+          vehicleNumber
+          make
+          model
+        }
+      }
+      drivers {
+        score
+        reasons
+        driver {
+          id
+          firstName
+          lastName
+          rating
+        }
+      }
+    }
+  }
+`;
+
+const RECORD_VEHICLE_SERVICE_MUTATION = `
+  mutation RecordVehicleService($id: ID!, $input: RecordVehicleServiceInput!) {
+    recordVehicleService(id: $id, input: $input) {
+      id
+      status
+      mileage
+      lastServiceDate
+      nextServiceDueDate
+      nextServiceDueMileage
+    }
+  }
+`;
+
+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]
+  );
+}
+
+interface AsyncResource<T> {
+  data: T;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+export function useFleetAlerts(): AsyncResource<FleetAlert[]> {
+  const graphQLOptions = useGraphqlOptions();
+  const [data, setData] = useState<FleetAlert[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+  const [nonce, setNonce] = useState(0);
+
+  useEffect(() => {
+    let active = true;
+    setIsLoading(true);
+    setError(null);
+    executeGraphQL<{ fleetAlerts: FleetAlert[] }>(graphQLOptions, FLEET_ALERTS_QUERY)
+      .then((result) => {
+        if (active) setData(result.fleetAlerts);
+      })
+      .catch((e: unknown) => {
+        if (active) setError(e instanceof Error ? e : new Error('Failed to load fleet alerts'));
+      })
+      .finally(() => {
+        if (active) setIsLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [graphQLOptions, nonce]);
+
+  const refetch = useCallback(() => setNonce((n) => n + 1), []);
+  return { data, isLoading, error, refetch };
+}
+
+const EMPTY_SUGGESTIONS: AssignmentSuggestions = { routeId: '', vehicles: [], drivers: [] };
+
+export function useAssignmentSuggestions(
+  routeId: string | undefined,
+  limit = 3
+): AsyncResource<AssignmentSuggestions> {
+  const graphQLOptions = useGraphqlOptions();
+  const [data, setData] = useState<AssignmentSuggestions>(EMPTY_SUGGESTIONS);
+  const [isLoading, setIsLoading] = useState(Boolean(routeId));
+  const [error, setError] = useState<Error | null>(null);
+  const [nonce, setNonce] = useState(0);
+
+  useEffect(() => {
+    if (!routeId) {
+      setData(EMPTY_SUGGESTIONS);
+      setIsLoading(false);
+      return undefined;
+    }
+    let active = true;
+    setIsLoading(true);
+    setError(null);
+    executeGraphQL<{ assignmentSuggestions: AssignmentSuggestions }>(
+      graphQLOptions,
+      ASSIGNMENT_SUGGESTIONS_QUERY,
+      { routeId, limit }
+    )
+      .then((result) => {
+        if (active) setData(result.assignmentSuggestions);
+      })
+      .catch((e: unknown) => {
+        if (active) setError(e instanceof Error ? e : new Error('Failed to load suggestions'));
+      })
+      .finally(() => {
+        if (active) setIsLoading(false);
+      });
+    return () => {
+      active = false;
+    };
+  }, [graphQLOptions, routeId, limit, nonce]);
+
+  const refetch = useCallback(() => setNonce((n) => n + 1), []);
+  return { data, isLoading, error, refetch };
+}
+
+export function useRecordVehicleService() {
+  const graphQLOptions = useGraphqlOptions();
+  return useCallback(
+    async (vehicleId: string, input: RecordVehicleServiceInput): Promise<void> => {
+      await executeGraphQL(graphQLOptions, RECORD_VEHICLE_SERVICE_MUTATION, {
+        id: vehicleId,
+        input,
+      });
+    },
+    [graphQLOptions]
+  );
+}

package/src/movethewheels/pages/FleetPage.tsx

@@ -20,6 +20,8 @@ import {
 } from '../components/ui';
 import { CTAOverflowMenu, EmphasisPanel, PagePurpose, NextSteps } from '@burdenoff/fe-libs/ui';
 import { useFleetStats, useVehicles, useDrivers } from '../hooks/useFleet';
+import { useFleetAlerts, type FleetAlert } from '../hooks/useFleetIntelligence';
+import { FleetAlertsPanel } from '../components/FleetAlertsPanel';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { useI18n } from '@burdenoff/fe-libs/shared/providers/shell/I18nProvider';
 import { joinPath } from '../utils/navigation';
@@ -50,6 +52,13 @@ export default function FleetPage() {
     refetch: refetchDrivers,
   } = useDrivers();
 
+  const {
+    data: alerts,
+    isLoading: alertsLoading,
+    error: alertsError,
+    refetch: refetchAlerts,
+  } = useFleetAlerts();
+
   const isLoading = statsLoading || vehiclesLoading || driversLoading;
   const error = statsError ?? vehiclesError ?? driversError;
   const refetchAll = () => {
@@ -64,6 +73,9 @@ export default function FleetPage() {
     }
   };
 
+  const openAlert = (alert: FleetAlert) =>
+    goTo(`fleet/${alert.subjectType === 'VEHICLE' ? 'vehicles' : 'drivers'}/${alert.subjectId}`);
+
   const onRowKeyDown = (e: React.KeyboardEvent, action: () => void) => {
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
@@ -136,6 +148,15 @@ export default function FleetPage() {
         ]}
       />
 
+      <FleetAlertsPanel
+        alerts={alerts}
+        isLoading={alertsLoading}
+        error={alertsError}
+        onRetry={refetchAlerts}
+        onOpen={openAlert}
+        t={t}
+      />
+
       {/* Key Metrics */}
       {error && !isLoading ? (
         <Card className="border-status-error-border">

package/src/movethewheels/pages/RouteDetailsPage.tsx

@@ -41,6 +41,9 @@ import { RouteMap, type RouteStop as MapRouteStop } from '../components/maps';
 import { firstRealLatLng } from '../utils/mapMarkers';
 import { useRoute, useRoutes } from '../hooks/useRoutes';
 import { useFleet } from '../hooks/useFleet';
+import { useAssignmentSuggestions } from '../hooks/useFleetIntelligence';
+import { AssignmentSuggestions } from '../components/AssignmentSuggestions';
+import { useI18n } from '@burdenoff/fe-libs/shared/providers/shell/I18nProvider';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate, formatAddress, formatCurrency } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
@@ -374,7 +377,13 @@ export default function RouteDetailsPage() {
   const isEditRoute = useLocation().pathname.endsWith('/edit');
   const { basePath, navigate } = useMoveTheWheels();
   const { route, isLoading, error, refetch } = useRoute(routeId);
-  const { optimizeRoute } = useRoutes();
+  const { optimizeRoute, updateRoute } = useRoutes();
+  const suggestions = useAssignmentSuggestions(routeId);
+  const { t: translate } = useI18n();
+  const t = (key: string, fallback: string): string => {
+    const value = translate(key);
+    return value === key ? fallback : value;
+  };
   const { message: notice, notify } = useNotice();
   const [optimizeError, setOptimizeError] = useState<string | null>(null);
   const [optimizing, setOptimizing] = useState(false);
@@ -397,6 +406,16 @@ export default function RouteDetailsPage() {
     }
   };
 
+  // A rejected assignment (vehicle in maintenance, licence expired, already on a
+  // live route) throws with the server's message, which the suggestions card shows.
+  const handleAssign = async (patch: { vehicleId?: string; driverId?: string }) => {
+    if (!routeId) return;
+    await updateRoute(routeId, patch);
+    notify(t('movethewheels.routes.suggest.done', 'Assignment saved.'));
+    refetch();
+    suggestions.refetch();
+  };
+
   // Handle new route form
   if (!routeId) {
     return <NewRouteForm />;
@@ -594,6 +613,19 @@ export default function RouteDetailsPage() {
         </div>
 
         <div className="space-y-6">
+          {(route.status === 'planned' || route.status === 'in_progress') && (
+            <AssignmentSuggestions
+              suggestions={suggestions.data}
+              isLoading={suggestions.isLoading}
+              error={suggestions.error}
+              onRetry={suggestions.refetch}
+              assignedVehicleId={route.vehicleId || undefined}
+              assignedDriverId={route.driverId || undefined}
+              onAssign={handleAssign}
+              t={t}
+            />
+          )}
+
           {/* Route Info — the page's single emphasis zone */}
           <EmphasisPanel className="space-y-4">
             <h2 className="text-base font-semibold text-text-primary">Route Info</h2>

package/src/movethewheels/pages/VehicleDetailsPage.tsx

@@ -26,10 +26,14 @@ import {
 } from '../components/ui';
 import { EmphasisPanel, NextSteps, PagePurpose } from '@burdenoff/fe-libs/ui';
 import { useVehicle, useVehicleDrivers, useFleet } from '../hooks/useFleet';
+import { useRecordVehicleService } from '../hooks/useFleetIntelligence';
+import { VehicleServiceCard } from '../components/VehicleServiceCard';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatDate, getInitials } from '../utils/formatters';
+import { useI18n } from '@burdenoff/fe-libs/shared/providers/shell/I18nProvider';
 import { joinPath } from '../utils/navigation';
 import { FormError } from '../components/FormError';
+import { Notice, useNotice } from '../components/Notice';
 import { DocumentsCard } from '../components/DocumentsCard';
 
 const VEHICLE_TYPE_OPTIONS = [
@@ -214,6 +218,13 @@ export default function VehicleDetailsPage() {
   const { vehicleId } = useParams<{ vehicleId: string }>();
   const { basePath, navigate } = useMoveTheWheels();
   const { vehicle, isLoading, error, refetch } = useVehicle(vehicleId);
+  const recordService = useRecordVehicleService();
+  const { message: notice, notify } = useNotice();
+  const { t: translate } = useI18n();
+  const t = (key: string, fallback: string): string => {
+    const value = translate(key);
+    return value === key ? fallback : value;
+  };
   const isEditRoute = useLocation().pathname.endsWith('/edit');
   // Who is behind the wheel — resolved through DriverFilterInput.vehicleId, the
   // same link `assignDriverVehicle` writes.
@@ -285,6 +296,12 @@ export default function VehicleDetailsPage() {
         ]}
       />
 
+      {notice && (
+        <div className="mb-2">
+          <Notice message={notice} />
+        </div>
+      )}
+
       <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
         <div className="lg:col-span-2 space-y-6">
           {/* Vehicle Information — the page's single emphasis zone */}
@@ -440,6 +457,16 @@ export default function VehicleDetailsPage() {
             </CardContent>
           </Card>
 
+          <VehicleServiceCard
+            vehicle={vehicle}
+            t={t}
+            onRecord={async (input) => {
+              await recordService(vehicle.id, input);
+              notify(t('movethewheels.vehicles.service.saved', 'Service recorded.'));
+              refetch();
+            }}
+          />
+
           {vehicle.currentLocation && (
             <Card>
               <CardHeader>

package/src/movethewheels/types/index.ts

@@ -341,6 +341,8 @@ export interface Vehicle {
   currentLocation?: Location;
   lastMaintenance?: Date;
   nextMaintenance?: Date;
+  /** Odometer reading (km) at which the next service is due. */
+  nextMaintenanceMileage?: number;
   fuelLevel?: number;
   mileage?: number;
   documents: VehicleDocument[];

package/src/movethewheels/utils/graphqlClient.ts

@@ -132,6 +132,19 @@ export async function executeGraphQL<TData>(
   }
 }
 
+/** Best-effort: the joined `errors[].message` of a non-2xx GraphQL response, or null. */
+async function readGraphqlErrorMessage(response: Response): Promise<string | null> {
+  try {
+    const payload = (await response.json()) as { errors?: Array<{ message?: string }> };
+    const messages = (payload.errors ?? [])
+      .map((item) => item.message)
+      .filter((message): message is string => typeof message === 'string' && message.length > 0);
+    return messages.length > 0 ? messages.join('; ') : null;
+  } catch {
+    return null;
+  }
+}
+
 async function runWithRetries<TData>(
   url: string,
   headers: Record<string, string>,
@@ -156,7 +169,13 @@ async function runWithRetries<TData>(
       });
 
       if (!response.ok) {
-        lastError = new Error(`GraphQL request failed with status ${response.status}`);
+        // Transient statuses are retried on the status alone. For anything else the
+        // service often answers 4xx with a well-formed GraphQL error (e.g. a business
+        // rule rejection) — show that message rather than a bare status code.
+        const detail = isTransientStatus(response.status)
+          ? null
+          : await readGraphqlErrorMessage(response);
+        lastError = new Error(detail ?? `GraphQL request failed with status ${response.status}`);
         if (canRetry && isTransientStatus(response.status)) continue;
         throw lastError;
       }