@burdenoff/microfe-movethewheels 2026.726.1 → 2026.731.1

package/src/movethewheels/hooks/useMultiModalShipments.ts

@@ -0,0 +1,323 @@
+/**
+ * Multi-modal freight execution (BOFF-4398).
+ *
+ * Wire shape matches wspace-movethewheels-svc: src/modules/shipment/schema/shipment.gql
+ * (MtwShipment, MtwShipmentLeg, MtwFreightRateQuote). Field names here are kept in
+ * lockstep with that schema — verify against the deployed schema before renaming
+ * anything (see BOFF-3922 schema-drift guard / prior MFE-schema-drift incidents).
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import { executeGraphQL } from '../utils/graphqlClient';
+
+export type TransportMode = 'ROAD' | 'AIR' | 'OCEAN' | 'RAIL';
+export type ShipmentLegStatus =
+  'PLANNED' | 'BOOKED' | 'IN_TRANSIT' | 'ARRIVED' | 'DELIVERED' | 'CANCELLED';
+export type OceanContainerType = 'LCL' | 'FCL_20FT' | 'FCL_40FT' | 'FCL_40FT_HC';
+
+export interface FreightRateBreakdownLine {
+  label: string;
+  amount: number;
+}
+
+export interface FreightRateQuote {
+  mode: TransportMode;
+  chargeableWeightKg?: number | null;
+  ratePerUnit: number;
+  calculatedCost: number;
+  currency: string;
+  breakdown: FreightRateBreakdownLine[];
+}
+
+export interface ShipmentLegDraft {
+  mode: TransportMode;
+  origin: { address?: string };
+  destination: { address?: string };
+  distanceKm?: number;
+  weightKg?: number;
+  lengthCm?: number;
+  widthCm?: number;
+  heightCm?: number;
+  volumeCbm?: number;
+  containerType?: OceanContainerType;
+  containerCount?: number;
+  carrierName?: string;
+}
+
+export interface ShipmentLeg extends ShipmentLegDraft {
+  id: string;
+  legNumber: number;
+  status: ShipmentLegStatus;
+  chargeableWeightKg?: number | null;
+  calculatedCost?: number | null;
+  currency: string;
+}
+
+export interface MultiModalShipment {
+  id: string;
+  shipmentNumber: string;
+  status: string;
+  primaryMode: TransportMode;
+  isMultiModal: boolean;
+  totalFreightCost?: number | null;
+  freightCurrency?: string | null;
+  origin: { address?: string };
+  destination: { address?: string };
+  createdAt: string;
+  legs: ShipmentLeg[];
+}
+
+interface ApiShipmentLeg {
+  id: string;
+  legNumber: number;
+  mode: TransportMode;
+  status: ShipmentLegStatus;
+  origin: Record<string, unknown> | null;
+  destination: Record<string, unknown> | null;
+  distanceKm?: number | null;
+  weightKg?: number | null;
+  lengthCm?: number | null;
+  widthCm?: number | null;
+  heightCm?: number | null;
+  volumeCbm?: number | null;
+  containerType?: OceanContainerType | null;
+  containerCount?: number | null;
+  carrierName?: string | null;
+  chargeableWeightKg?: number | null;
+  calculatedCost?: number | null;
+  currency: string;
+}
+
+interface ApiShipment {
+  id: string;
+  shipmentNumber: string;
+  status: string;
+  primaryMode: TransportMode;
+  isMultiModal: boolean;
+  totalFreightCost?: number | null;
+  freightCurrency?: string | null;
+  origin: Record<string, unknown> | null;
+  destination: Record<string, unknown> | null;
+  createdAt: string;
+  legs: ApiShipmentLeg[];
+}
+
+const LEG_FIELDS = `
+  id
+  legNumber
+  mode
+  status
+  origin
+  destination
+  distanceKm
+  weightKg
+  lengthCm
+  widthCm
+  heightCm
+  volumeCbm
+  containerType
+  containerCount
+  carrierName
+  chargeableWeightKg
+  calculatedCost
+  currency
+`;
+
+const SHIPMENT_FIELDS = `
+  id
+  shipmentNumber
+  status
+  primaryMode
+  isMultiModal
+  totalFreightCost
+  freightCurrency
+  origin
+  destination
+  createdAt
+  legs {
+    ${LEG_FIELDS}
+  }
+`;
+
+const MULTI_MODAL_SHIPMENTS_QUERY = `
+  query ListMultiModalShipments($pagination: PaginationInput) {
+    shipments(filter: { isMultiModal: true }, pagination: $pagination) {
+      ${SHIPMENT_FIELDS}
+    }
+  }
+`;
+
+const CALCULATE_FREIGHT_RATE_QUERY = `
+  query CalculateFreightRate($input: FreightRateInput!) {
+    calculateFreightRate(input: $input) {
+      mode
+      chargeableWeightKg
+      ratePerUnit
+      calculatedCost
+      currency
+      breakdown {
+        label
+        amount
+      }
+    }
+  }
+`;
+
+const PLAN_MULTI_MODAL_SHIPMENT_MUTATION = `
+  mutation PlanMultiModalShipment($input: PlanMultiModalShipmentInput!) {
+    planMultiModalShipment(input: $input) {
+      ${SHIPMENT_FIELDS}
+    }
+  }
+`;
+
+function toApiLeg(leg: ShipmentLegDraft) {
+  return {
+    mode: leg.mode,
+    origin: leg.origin,
+    destination: leg.destination,
+    distanceKm: leg.distanceKm,
+    weightKg: leg.weightKg,
+    lengthCm: leg.lengthCm,
+    widthCm: leg.widthCm,
+    heightCm: leg.heightCm,
+    volumeCbm: leg.volumeCbm,
+    containerType: leg.containerType,
+    containerCount: leg.containerCount,
+    carrierName: leg.carrierName,
+  };
+}
+
+function mapLeg(leg: ApiShipmentLeg): ShipmentLeg {
+  return {
+    id: leg.id,
+    legNumber: leg.legNumber,
+    mode: leg.mode,
+    status: leg.status,
+    origin: (leg.origin as { address?: string } | null) ?? {},
+    destination: (leg.destination as { address?: string } | null) ?? {},
+    distanceKm: leg.distanceKm ?? undefined,
+    weightKg: leg.weightKg ?? undefined,
+    lengthCm: leg.lengthCm ?? undefined,
+    widthCm: leg.widthCm ?? undefined,
+    heightCm: leg.heightCm ?? undefined,
+    volumeCbm: leg.volumeCbm ?? undefined,
+    containerType: leg.containerType ?? undefined,
+    containerCount: leg.containerCount ?? undefined,
+    carrierName: leg.carrierName ?? undefined,
+    chargeableWeightKg: leg.chargeableWeightKg,
+    calculatedCost: leg.calculatedCost,
+    currency: leg.currency,
+  };
+}
+
+function mapShipment(shipment: ApiShipment): MultiModalShipment {
+  return {
+    id: shipment.id,
+    shipmentNumber: shipment.shipmentNumber,
+    status: shipment.status,
+    primaryMode: shipment.primaryMode,
+    isMultiModal: shipment.isMultiModal,
+    totalFreightCost: shipment.totalFreightCost,
+    freightCurrency: shipment.freightCurrency,
+    origin: (shipment.origin as { address?: string } | null) ?? {},
+    destination: (shipment.destination as { address?: string } | null) ?? {},
+    createdAt: shipment.createdAt,
+    legs: (shipment.legs ?? []).map(mapLeg),
+  };
+}
+
+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]
+  );
+}
+
+export function useMultiModalShipments() {
+  const graphQLOptions = useGraphqlOptions();
+  const [shipments, setShipments] = useState<MultiModalShipment[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const data = await executeGraphQL<{ shipments: ApiShipment[] }>(
+        graphQLOptions,
+        MULTI_MODAL_SHIPMENTS_QUERY,
+        { pagination: { limit: 100, offset: 0 } }
+      );
+      setShipments(data.shipments.map(mapShipment));
+    } catch (fetchError) {
+      setError(
+        fetchError instanceof Error ? fetchError : new Error('Failed to load multi-modal shipments')
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [graphQLOptions]);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const calculateFreightRate = useCallback(
+    async (leg: ShipmentLegDraft): Promise<FreightRateQuote> => {
+      const data = await executeGraphQL<{ calculateFreightRate: FreightRateQuote }>(
+        graphQLOptions,
+        CALCULATE_FREIGHT_RATE_QUERY,
+        { input: toApiLeg(leg) }
+      );
+      return data.calculateFreightRate;
+    },
+    [graphQLOptions]
+  );
+
+  const planMultiModalShipment = useCallback(
+    async (input: {
+      shipmentNumber: string;
+      customerId?: string;
+      origin: { address?: string };
+      destination: { address?: string };
+      legs: ShipmentLegDraft[];
+    }): Promise<MultiModalShipment> => {
+      const data = await executeGraphQL<{ planMultiModalShipment: ApiShipment }>(
+        graphQLOptions,
+        PLAN_MULTI_MODAL_SHIPMENT_MUTATION,
+        {
+          input: {
+            shipmentNumber: input.shipmentNumber,
+            customerId: input.customerId,
+            origin: input.origin,
+            destination: input.destination,
+            legs: input.legs.map(toApiLeg),
+          },
+        }
+      );
+      const created = mapShipment(data.planMultiModalShipment);
+      setShipments((previous) => [created, ...previous]);
+      return created;
+    },
+    [graphQLOptions]
+  );
+
+  return {
+    shipments,
+    isLoading,
+    error,
+    refetch: () => void load(),
+    calculateFreightRate,
+    planMultiModalShipment,
+  };
+}

package/src/movethewheels/pages/DashboardPage.tsx

@@ -16,6 +16,7 @@ import {
   MapPin,
   ChevronRight,
   Activity,
+  Ship,
 } from 'lucide-react';
 import { PageLayout, PageSection } from '../components/PageLayout';
 import { MetricCard, MetricGrid, type MetricDelta } from '../components/MetricCard';
@@ -158,6 +159,11 @@ export default function DashboardPage() {
               icon: <MapPin size={16} />,
               onSelect: () => goTo('tracking/live'),
             },
+            {
+              label: t('movethewheels.dashboard.actions.multiModal', 'Multi-Modal Freight'),
+              icon: <Ship size={16} />,
+              onSelect: () => goTo('shipments/multi-modal'),
+            },
           ]}
         />
       }

package/src/movethewheels/pages/DeliveryCapturePage.tsx

@@ -0,0 +1,297 @@
+/**
+ * Delivery Capture Page — driver-facing electronic proof-of-delivery (ePOD)
+ * capture flow (BOFF-4399).
+ *
+ * Lists the calling driver's own delivery jobs still awaiting capture
+ * (`myPendingEpodDeliveryJobs`, Type C self-list — no other driver's jobs are
+ * ever visible here) and lets them capture: recipient name, signature
+ * (drawn or typed), an optional delivery photo (uploaded via the platform
+ * files primitive), device GPS if available, and notes. Submitting calls
+ * `captureEpod`, which the backend owner-verifies against the assigned
+ * driver and marks the job DELIVERED.
+ *
+ * Deferred (see BOFF-4399 follow-up notes): barcode/RFID scan-based capture,
+ * multi-language delivery instructions, and the full standalone mobile
+ * driver app (BOFF-3991) — this page is the capture core, reachable from the
+ * existing web MFE.
+ */
+import { useRef, useState } from 'react';
+import {
+  CheckCircle2,
+  Loader2,
+  MapPin,
+  Package,
+  PenLine,
+  Truck,
+  Type as TypeIcon,
+  Upload,
+} from 'lucide-react';
+import { PageLayout } from '../components/PageLayout';
+import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Textarea } from '../components/ui';
+import { SignaturePad, type SignaturePadHandle } from '../components/SignaturePad';
+import { FormError } from '../components/FormError';
+import { Notice, useNotice } from '../components/Notice';
+import {
+  useCaptureEpod,
+  useEpodPhotoUpload,
+  useMyPendingEpodDeliveryJobs,
+  type PendingEpodDeliveryJob,
+} from '../hooks/useEpod';
+import { formatAddress, formatDate } from '../utils/formatters';
+import type { SignatureType } from '../types';
+
+/** Resolves the device's current position, if the browser grants it. Never blocks submission. */
+function getCurrentPosition(): Promise<GeolocationPosition | null> {
+  return new Promise((resolve) => {
+    if (!navigator.geolocation) {
+      resolve(null);
+      return;
+    }
+    navigator.geolocation.getCurrentPosition(
+      (position) => resolve(position),
+      () => resolve(null),
+      { enableHighAccuracy: true, timeout: 8000, maximumAge: 30000 }
+    );
+  });
+}
+
+function CaptureForm({
+  job,
+  onCaptured,
+  onCancel,
+}: {
+  job: PendingEpodDeliveryJob;
+  onCaptured: () => void;
+  onCancel: () => void;
+}) {
+  const { captureEpod, isSubmitting, error: captureError } = useCaptureEpod();
+  const { upload: uploadPhoto, isUploading, error: uploadError } = useEpodPhotoUpload();
+  const signaturePadRef = useRef<SignaturePadHandle>(null);
+
+  const [recipientName, setRecipientName] = useState('');
+  const [signatureType, setSignatureType] = useState<SignatureType>('drawn');
+  const [typedSignature, setTypedSignature] = useState('');
+  const [photoFile, setPhotoFile] = useState<File | null>(null);
+  const [notes, setNotes] = useState('');
+  const [validationError, setValidationError] = useState<string | null>(null);
+
+  const handleSubmit = async () => {
+    setValidationError(null);
+
+    const trimmedRecipient = recipientName.trim();
+    if (!trimmedRecipient) {
+      setValidationError('Recipient name is required.');
+      return;
+    }
+
+    const signatureData =
+      signatureType === 'typed' ? typedSignature.trim() : signaturePadRef.current?.toDataUrl() ?? null;
+    if (!signatureData) {
+      setValidationError(
+        signatureType === 'typed' ? 'Type the recipient full name as their signature.' : 'A signature is required.'
+      );
+      return;
+    }
+
+    try {
+      let photoFileIds: string[] | undefined;
+      if (photoFile) {
+        const uploaded = await uploadPhoto(photoFile);
+        photoFileIds = [uploaded.fileId];
+      }
+
+      const position = await getCurrentPosition();
+
+      await captureEpod({
+        deliveryJobId: job.id,
+        recipientName: trimmedRecipient,
+        signatureType,
+        signatureData,
+        photoFileIds,
+        latitude: position?.coords.latitude,
+        longitude: position?.coords.longitude,
+        locationAccuracy: position?.coords.accuracy,
+        notes: notes.trim() || undefined,
+      });
+
+      onCaptured();
+    } catch {
+      // captureError / uploadError already carry the message for display below.
+    }
+  };
+
+  const submitting = isSubmitting || isUploading;
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle className="flex items-center gap-2">
+          <Truck size={18} /> Capture delivery for {job.deliveryJobNumber}
+        </CardTitle>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="text-sm text-text-secondary space-y-1">
+          {job.customerName && <p>Recipient on file: {job.customerName}</p>}
+          {job.deliveryAddress && <p>{formatAddress(job.deliveryAddress)}</p>}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-recipient-name">Recipient name</Label>
+          <Input
+            id="epod-recipient-name"
+            value={recipientName}
+            onChange={(event) => setRecipientName(event.target.value)}
+            placeholder="Who received the delivery?"
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label>Signature</Label>
+          <div className="flex gap-2">
+            <Button
+              type="button"
+              variant={signatureType === 'drawn' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('drawn')}
+            >
+              <PenLine size={14} /> Draw
+            </Button>
+            <Button
+              type="button"
+              variant={signatureType === 'typed' ? 'default' : 'outline'}
+              size="sm"
+              onClick={() => setSignatureType('typed')}
+            >
+              <TypeIcon size={14} /> Type name instead
+            </Button>
+          </div>
+          {signatureType === 'drawn' ? (
+            <SignaturePad ref={signaturePadRef} />
+          ) : (
+            <Input
+              value={typedSignature}
+              onChange={(event) => setTypedSignature(event.target.value)}
+              placeholder="Type full name as signature"
+            />
+          )}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-photo">Delivery photo (optional)</Label>
+          <div className="flex items-center gap-2">
+            <input
+              id="epod-photo"
+              type="file"
+              accept="image/*"
+              capture="environment"
+              onChange={(event) => setPhotoFile(event.target.files?.[0] ?? null)}
+              className="text-sm"
+            />
+            {photoFile && <Upload size={14} className="text-text-secondary" />}
+          </div>
+          {photoFile && <p className="text-xs text-text-secondary">{photoFile.name}</p>}
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="epod-notes">Notes (optional)</Label>
+          <Textarea
+            id="epod-notes"
+            value={notes}
+            onChange={(event) => setNotes(event.target.value)}
+            placeholder="e.g. Left with front desk, gate code used, etc."
+            rows={2}
+          />
+        </div>
+
+        <p className="flex items-center gap-1.5 text-xs text-text-secondary">
+          <MapPin size={12} /> Device GPS is captured automatically when permitted by the browser.
+        </p>
+
+        {validationError && <FormError message={validationError} />}
+        {captureError && <FormError message={captureError.message} />}
+        {uploadError && <FormError message={uploadError.message} />}
+
+        <div className="flex gap-2 justify-end">
+          <Button type="button" variant="outline" onClick={onCancel} disabled={submitting}>
+            Cancel
+          </Button>
+          <Button type="button" onClick={() => void handleSubmit()} disabled={submitting}>
+            {submitting ? (
+              <>
+                <Loader2 size={14} className="animate-spin" /> Submitting…
+              </>
+            ) : (
+              <>
+                <CheckCircle2 size={14} /> Confirm delivery
+              </>
+            )}
+          </Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default function DeliveryCapturePage() {
+  const { jobs, isLoading, error, refetch } = useMyPendingEpodDeliveryJobs();
+  const [selectedJob, setSelectedJob] = useState<PendingEpodDeliveryJob | null>(null);
+  const { message, notify } = useNotice();
+
+  const handleCaptured = () => {
+    notify('Proof of delivery captured — delivery marked complete.');
+    setSelectedJob(null);
+    refetch();
+  };
+
+  return (
+    <PageLayout
+      title="My Deliveries"
+      subtitle="Capture proof of delivery for your assigned stops"
+      icon={<Truck size={24} />}
+    >
+      <div className="space-y-4">
+        <Notice message={message} />
+
+        {selectedJob ? (
+          <CaptureForm job={selectedJob} onCaptured={handleCaptured} onCancel={() => setSelectedJob(null)} />
+        ) : isLoading ? (
+          <p className="text-text-secondary text-center py-8">Loading your deliveries…</p>
+        ) : error ? (
+          <FormError message={error.message} />
+        ) : jobs.length > 0 ? (
+          <div className="space-y-3">
+            {jobs.map((job) => (
+              <Card key={job.id}>
+                <CardContent className="flex items-center justify-between gap-3 py-4">
+                  <div className="min-w-0">
+                    <p className="font-medium flex items-center gap-2">
+                      <Package size={16} /> {job.deliveryJobNumber}
+                    </p>
+                    {job.deliveryAddress && (
+                      <p className="text-sm text-text-secondary truncate">
+                        {formatAddress(job.deliveryAddress)}
+                      </p>
+                    )}
+                    {job.scheduledDelivery && (
+                      <p className="text-xs text-text-secondary">
+                        Scheduled {formatDate(job.scheduledDelivery, 'short')}
+                      </p>
+                    )}
+                  </div>
+                  <Button type="button" size="sm" onClick={() => setSelectedJob(job)}>
+                    Capture
+                  </Button>
+                </CardContent>
+              </Card>
+            ))}
+          </div>
+        ) : (
+          <div className="text-center py-12">
+            <CheckCircle2 size={40} className="mx-auto mb-3 text-text-secondary opacity-50" />
+            <p className="text-text-secondary">No deliveries awaiting proof of delivery.</p>
+          </div>
+        )}
+      </div>
+    </PageLayout>
+  );
+}