@burdenoff/microfe-movethewheels 2026.1031.1 → 2026.1031.3

package/src/movethewheels/utils/entityImport.ts

@@ -0,0 +1,239 @@
+/**
+ * Entity import — client side of wspace-movethewheels-svc's bulk import (BOFF-3990).
+ *
+ * The service owns parsing and validation; this module only picks the right
+ * mutation for an entity, detects the file format, builds CSV templates from
+ * the server's column specification and shapes the result for display.
+ * Kept free of React so the contract can be unit-tested.
+ */
+
+export const MTW_IMPORT_ENTITIES = [
+  { entityType: 'CUSTOMER', label: 'Customers', noun: 'customer', field: 'importMtwCustomers' },
+  { entityType: 'VEHICLE', label: 'Vehicles', noun: 'vehicle', field: 'importMtwVehicles' },
+  { entityType: 'DRIVER', label: 'Drivers', noun: 'driver', field: 'importMtwDrivers' },
+  { entityType: 'WAREHOUSE', label: 'Warehouses', noun: 'warehouse', field: 'importMtwWarehouses' },
+  { entityType: 'CARGO_ITEM', label: 'Products', noun: 'product', field: 'importMtwCargoItems' },
+] as const;
+
+export type MtwImportEntityType = (typeof MTW_IMPORT_ENTITIES)[number]['entityType'];
+export type MtwImportFormat = 'CSV' | 'JSON';
+export type MtwImportStatus = 'DRY_RUN' | 'COMPLETED' | 'PARTIAL' | 'REJECTED';
+
+/** Mirrors the service limits so an oversized file is refused before upload. */
+export const MTW_IMPORT_MAX_BYTES = 2 * 1024 * 1024;
+export const MTW_IMPORT_MAX_ROWS = 1000;
+
+export function isImportEntityType(value: string | null | undefined): value is MtwImportEntityType {
+  return MTW_IMPORT_ENTITIES.some((entity) => entity.entityType === value);
+}
+
+export function importEntity(entityType: MtwImportEntityType) {
+  const entity = MTW_IMPORT_ENTITIES.find((candidate) => candidate.entityType === entityType);
+  if (!entity) throw new Error(`Unknown import entity ${entityType}`);
+  return entity;
+}
+
+// One static document per entity so graphql-schema-drift can validate each
+// against the subgraph schema; the selection sets are identical.
+export const IMPORT_MUTATIONS: Record<MtwImportEntityType, string> = {
+  CUSTOMER: `
+    mutation ImportMtwCustomers($input: MtwImportInput!) {
+      importMtwCustomers(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  VEHICLE: `
+    mutation ImportMtwVehicles($input: MtwImportInput!) {
+      importMtwVehicles(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  DRIVER: `
+    mutation ImportMtwDrivers($input: MtwImportInput!) {
+      importMtwDrivers(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  WAREHOUSE: `
+    mutation ImportMtwWarehouses($input: MtwImportInput!) {
+      importMtwWarehouses(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+  CARGO_ITEM: `
+    mutation ImportMtwCargoItems($input: MtwImportInput!) {
+      importMtwCargoItems(input: $input) {
+        entityType
+        status
+        dryRun
+        totalRows
+        validRows
+        importedRows
+        failedRows
+        createdIds
+        errorsTruncated
+        errors {
+          row
+          field
+          message
+        }
+      }
+    }
+  `,
+};
+
+/** The mutation document for one entity's import. */
+export function importMutation(entityType: MtwImportEntityType): string {
+  return IMPORT_MUTATIONS[importEntity(entityType).entityType];
+}
+
+export const MTW_IMPORT_SPEC_QUERY = `
+  query MtwImportSpec {
+    mtwImportSpec {
+      entityType
+      keyColumn
+      columns {
+        name
+        type
+        required
+        description
+        allowedValues
+        maxLength
+        min
+        max
+      }
+    }
+  }
+`;
+
+export interface MtwImportColumn {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string;
+  allowedValues: string[] | null;
+  maxLength: number | null;
+  min: number | null;
+  max: number | null;
+}
+
+export interface MtwImportEntitySpec {
+  entityType: MtwImportEntityType;
+  keyColumn: string | null;
+  columns: MtwImportColumn[];
+}
+
+export interface MtwImportRowError {
+  row: number;
+  field: string | null;
+  message: string;
+}
+
+export interface MtwImportResult {
+  entityType: MtwImportEntityType;
+  status: MtwImportStatus;
+  dryRun: boolean;
+  totalRows: number;
+  validRows: number;
+  importedRows: number;
+  failedRows: number;
+  createdIds: string[];
+  errorsTruncated: boolean;
+  errors: MtwImportRowError[];
+}
+
+/** Picks the format from the file name, falling back to the MIME type. */
+export function detectImportFormat(fileName: string, mimeType = ''): MtwImportFormat | null {
+  const lower = fileName.toLowerCase();
+  if (lower.endsWith('.csv')) return 'CSV';
+  if (lower.endsWith('.json')) return 'JSON';
+  if (mimeType.includes('csv')) return 'CSV';
+  if (mimeType.includes('json')) return 'JSON';
+  return null;
+}
+
+function csvCell(value: string): string {
+  return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+/** A CSV template: the header row, required columns first, then optional ones. */
+export function buildCsvTemplate(spec: MtwImportEntitySpec): string {
+  const ordered = [
+    ...spec.columns.filter((column) => column.required),
+    ...spec.columns.filter((column) => !column.required),
+  ];
+  return `${ordered.map((column) => csvCell(column.name)).join(',')}\n`;
+}
+
+/** One-line summary of an import result for the status banner. */
+export function summariseImport(result: MtwImportResult, noun: string): string {
+  const rows = (count: number) => `${count} ${noun}${count === 1 ? '' : 's'}`;
+  switch (result.status) {
+    case 'DRY_RUN':
+      return result.failedRows === 0
+        ? `All ${rows(result.totalRows)} are valid. Nothing was imported yet.`
+        : `${result.validRows} of ${rows(result.totalRows)} are valid; ${result.failedRows} need fixing. Nothing was imported.`;
+    case 'COMPLETED':
+      return `Imported ${rows(result.importedRows)}.`;
+    case 'PARTIAL':
+      return `Imported ${rows(result.importedRows)}; ${result.failedRows} row${result.failedRows === 1 ? '' : 's'} failed.`;
+    case 'REJECTED':
+      return `Nothing was imported: ${result.failedRows} of ${result.totalRows} rows have problems. Fix them, or allow a partial import.`;
+  }
+}

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`;
+}