@burdenoff/microfe-movethewheels 2026.1010.2 → 2026.1011.1

package/src/movethewheels/MoveTheWheelsRoot.tsx

@@ -92,6 +92,14 @@ const NavRegistrar: FC<Pick<MoveTheWheelsRootProps, 'registerNavItems' | 'basePa
           path: joinPath(basePath, 'tracking'),
           icon: <Map size={16} />,
           order: 3,
+          children: [
+            {
+              id: 'mtw-tracking-quality',
+              label: tr('movethewheels.root.nav.trackingQuality', 'Tracking event quality'),
+              path: joinPath(basePath, 'tracking/event-quality'),
+              icon: <Map size={16} />,
+            },
+          ],
         },
         {
           id: 'mtw-consolidation',

package/src/movethewheels/MoveTheWheelsRoutes.tsx

@@ -55,6 +55,7 @@ const OrdersListPage = lazy(() => import('./pages/OrdersListPage'));
 const OrderDetailsPage = lazy(() => import('./pages/OrderDetailsPage'));
 const CreateOrderPage = lazy(() => import('./pages/CreateOrderPage'));
 const TrackingPage = lazy(() => import('./pages/TrackingPage'));
+const TrackingEventQualityPage = lazy(() => import('./pages/TrackingEventQualityPage'));
 const LiveTrackingPage = lazy(() => import('./pages/LiveTrackingPage'));
 const FleetPage = lazy(() => import('./pages/FleetPage'));
 const VehiclesPage = lazy(() => import('./pages/VehiclesPage'));
@@ -108,6 +109,7 @@ export function MoveTheWheelsRoutes() {
         {/* Tracking */}
         <Route path="tracking" element={<TrackingPage />} />
         <Route path="tracking/live" element={<LiveTrackingPage />} />
+        <Route path="tracking/event-quality" element={<TrackingEventQualityPage />} />
 
         {/* Driver ePOD capture (BOFF-4399) */}
         <Route path="deliveries/mine" element={<DeliveryCapturePage />} />

package/src/movethewheels/hooks/useTrackingEventQuality.ts

@@ -0,0 +1,68 @@
+import {
+  TrackingQualityIntegrationsDocument,
+  TrackingQualityDeliveriesDocument,
+  TrackingQualityShipmentDocument,
+} from '../../generated/tracking-quality-operations';
+export {
+  TrackingQualityIntegrationsDocument as QualityIntegrationsDocument,
+  TrackingQualityDeliveriesDocument as QualityDeliveriesDocument,
+  TrackingQualityShipmentDocument as QualityShipmentDocument,
+};
+
+export interface TrackingUpdateOutcome {
+  index: number;
+  externalEventId: string | null;
+  shipmentReference: string;
+  shipmentId: string | null;
+  status: 'ACCEPTED' | 'DUPLICATE' | 'CONFLICT' | 'REJECTED';
+  errorCode: string | null;
+}
+
+const statuses = new Set(['ACCEPTED', 'DUPLICATE', 'CONFLICT', 'REJECTED']);
+const codes = new Set([
+  'KEY_CONFLICT',
+  'BUDGET_EXHAUSTED',
+  'INTEGRATION_UNAVAILABLE',
+  'SHIPMENT_UNAVAILABLE',
+  'UPDATE_REJECTED',
+]);
+const bounded = (value: unknown, max: number): value is string =>
+  typeof value === 'string' && value.length <= max;
+const nullable = (value: unknown, max: number): value is string | null =>
+  value === null || bounded(value, max);
+
+/** JSON scalar decoding fails closed; legacy delivery history has no outcomes. */
+export function trackingOutcomes(value: unknown): TrackingUpdateOutcome[] | null {
+  if (!Array.isArray(value) || value.length > 5) return null;
+  const result: TrackingUpdateOutcome[] = [];
+  for (const item of value) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) return null;
+    const row: Record<string, unknown> = item;
+    if (
+      !Number.isInteger(row.index) ||
+      typeof row.index !== 'number' ||
+      row.index !== result.length ||
+      row.index < 0 ||
+      row.index > 4 ||
+      !nullable(row.externalEventId, 255) ||
+      !bounded(row.shipmentReference, 255) ||
+      !nullable(row.shipmentId, 255) ||
+      typeof row.status !== 'string' ||
+      !statuses.has(row.status) ||
+      (row.status === 'CONFLICT' && row.shipmentId !== null) ||
+      !(row.errorCode === null || (typeof row.errorCode === 'string' && codes.has(row.errorCode)))
+    ) {
+      return null;
+    }
+    // The finite status/code guards justify narrowing the untyped JSON scalar.
+    result.push({
+      index: row.index,
+      externalEventId: row.externalEventId,
+      shipmentReference: row.shipmentReference,
+      shipmentId: row.shipmentId,
+      status: row.status as TrackingUpdateOutcome['status'],
+      errorCode: row.errorCode,
+    });
+  }
+  return result;
+}

package/src/movethewheels/pages/TrackingEventQualityPage.tsx

@@ -0,0 +1,239 @@
+import { useState } from 'react';
+import { RadioTower } from 'lucide-react';
+import { PageLayout } from '../components/PageLayout';
+import { Button } from '../components/ui';
+import { reuseCard, reuseSelect, ReuseState } from '../components/ReuseControls';
+import { useConditionQuery } from '../hooks/useContainerCondition';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import {
+  QualityIntegrationsDocument,
+  QualityDeliveriesDocument,
+  QualityShipmentDocument,
+  trackingOutcomes,
+} from '../hooks/useTrackingEventQuality';
+import type {
+  TrackingQualityIntegrationsQuery,
+  TrackingQualityDeliveriesQuery,
+  TrackingQualityShipmentQuery,
+} from '../../generated/tracking-quality-operations';
+
+const LIMIT = 20;
+function Pager({
+  offset,
+  length,
+  busy,
+  onChange,
+}: {
+  offset: number;
+  length: number | undefined;
+  busy: boolean;
+  onChange: (offset: number) => void;
+}) {
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <Button
+        variant="outline"
+        disabled={busy || offset === 0}
+        onClick={() => onChange(Math.max(0, offset - LIMIT))}
+      >
+        Previous page
+      </Button>
+      <span>{length === undefined ? 'Page unavailable' : `${length} records on this page`}</span>
+      <Button
+        variant="outline"
+        disabled={busy || length !== LIMIT || offset >= 9980}
+        onClick={() => onChange(offset + LIMIT)}
+      >
+        Next page
+      </Button>
+    </div>
+  );
+}
+
+export default function TrackingEventQualityPage() {
+  const { workspaceId, tenantId, currentUser, apiGatewayUrl } = useMoveTheWheels();
+  return (
+    <PageLayout
+      title="Tracking event quality"
+      subtitle="Review delivery results before investigating a shipment."
+      icon={<RadioTower aria-hidden="true" />}
+    >
+      <QualityWorkbench key={`${workspaceId}:${tenantId}:${currentUser?.id}:${apiGatewayUrl}`} />
+    </PageLayout>
+  );
+}
+function QualityWorkbench() {
+  const [integrationOffset, setIntegrationOffset] = useState(0);
+  const [selected, setSelected] = useState('');
+  const [offset, setOffset] = useState(0);
+  const [revision, setRevision] = useState(0);
+  const [shipmentId, setShipmentId] = useState<string | null>(null);
+  const integrations = useConditionQuery<TrackingQualityIntegrationsQuery>(
+    QualityIntegrationsDocument,
+    { pagination: { limit: LIMIT, offset: integrationOffset } },
+    revision
+  );
+  const deliveries = useConditionQuery<TrackingQualityDeliveriesQuery>(
+    QualityDeliveriesDocument,
+    selected ? { id: selected, pagination: { limit: LIMIT, offset } } : null,
+    revision
+  );
+  const options = integrations.data?.integrations;
+  const records = deliveries.data?.integration?.events;
+  return (
+    <div className="space-y-6">
+      <p>
+        Matching event keys and payloads create no additional tracking event. A changed payload with
+        the same key is a conflict. Updates without a key can create new events.
+      </p>
+      <p>
+        Each delivery admits at most five updates. An oversized or malformed delivery is rejected
+        before updates are recorded. Delivery history can include older records without item
+        results.
+      </p>
+      <section className={reuseCard} aria-label="Integration selection">
+        <ReuseState loading={integrations.loading} error={integrations.error} />
+        {options?.length === 0 && <p>No integrations on this page.</p>}
+        <label className="block">
+          Integration
+          <select
+            className={reuseSelect}
+            value={selected}
+            disabled={!options || integrations.loading}
+            onChange={(event) => {
+              setSelected(event.target.value);
+              setOffset(0);
+              setShipmentId(null);
+            }}
+          >
+            <option value="">Choose an integration</option>
+            {options?.map((integration) => (
+              <option key={integration.id} value={integration.id}>
+                {integration.name} · {integration.provider} · {integration.status}
+              </option>
+            ))}
+          </select>
+        </label>
+        <Pager
+          offset={integrationOffset}
+          length={options?.length}
+          busy={integrations.loading}
+          onChange={(next) => {
+            setIntegrationOffset(next);
+            setSelected('');
+            setOffset(0);
+            setShipmentId(null);
+          }}
+        />
+      </section>
+      {selected && (
+        <section className={reuseCard} aria-label="Tracking delivery history">
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <h2 className="text-lg font-semibold">Delivery history</h2>
+            <Button
+              variant="outline"
+              disabled={deliveries.loading}
+              onClick={() => setRevision((value) => value + 1)}
+            >
+              Refresh results
+            </Button>
+          </div>
+          <ReuseState loading={deliveries.loading} error={deliveries.error} />
+          {deliveries.data?.integration === null && (
+            <p role="status">Integration unavailable in this workspace.</p>
+          )}
+          {records?.length === 0 && <p>No deliveries on this page.</p>}
+          {records?.map((delivery) => {
+            const outcomes = trackingOutcomes(delivery.outcomes);
+            return (
+              <article key={delivery.id} className="space-y-3 rounded-lg border p-4">
+                <h3 className="font-semibold">
+                  {delivery.status} · {new Date(delivery.receivedAt).toLocaleString()}
+                </h3>
+                {outcomes === null ? (
+                  <p>Per-update results unavailable for this delivery.</p>
+                ) : outcomes.length === 0 ? (
+                  <p>
+                    No normalized updates were attempted. This is not a count of raw sender items.
+                  </p>
+                ) : (
+                  <ol className="space-y-3">
+                    {outcomes.map((outcome) => (
+                      <li key={outcome.index} className="break-words rounded-md bg-bg-surface p-3">
+                        <p>
+                          Update {outcome.index + 1}: <strong>{outcome.status}</strong>
+                        </p>
+                        <p>Event key: {outcome.externalEventId ?? 'Missing — not deduplicated'}</p>
+                        <p>Shipment reference: {outcome.shipmentReference || 'Not recorded'}</p>
+                        {outcome.errorCode && (
+                          <p>Reason: {outcome.errorCode.replaceAll('_', ' ').toLowerCase()}</p>
+                        )}
+                        {outcome.status === 'CONFLICT' && (
+                          <p>The earlier receipt stays unchanged; this update adds no event.</p>
+                        )}
+                        {outcome.shipmentId && (
+                          <Button
+                            variant="outline"
+                            onClick={() => setShipmentId(outcome.shipmentId)}
+                          >
+                            View shipment
+                          </Button>
+                        )}
+                      </li>
+                    ))}
+                  </ol>
+                )}
+              </article>
+            );
+          })}
+          <Pager
+            offset={offset}
+            length={records?.length}
+            busy={deliveries.loading}
+            onChange={setOffset}
+          />
+        </section>
+      )}
+      {shipmentId && (
+        <QualityShipment key={shipmentId} id={shipmentId} onClose={() => setShipmentId(null)} />
+      )}
+      <p className="text-sm text-text-secondary">
+        These results describe recorded ingestion, not physical shipment truth. Ordering, late
+        updates and provider corrections need separate policies.
+      </p>
+    </div>
+  );
+}
+
+function QualityShipment({ id, onClose }: { id: string; onClose: () => void }) {
+  const query = useConditionQuery<TrackingQualityShipmentQuery>(QualityShipmentDocument, { id });
+  return (
+    <section className={reuseCard} aria-label="Shipment tracking summary">
+      <h2 className="text-lg font-semibold">Shipment tracking summary</h2>
+      <Button variant="outline" onClick={onClose}>
+        Close shipment summary
+      </Button>
+      <ReuseState loading={query.loading} error={query.error} />
+      {query.data?.shipment === null && <p>Shipment unavailable in this workspace.</p>}
+      {query.data?.shipment && (
+        <>
+          <p>
+            {query.data.shipment.shipmentNumber} · {query.data.shipment.status}
+          </p>
+          <p>Tracking number: {query.data.shipment.trackingNumber ?? 'Not recorded'}</p>
+          <p>
+            {query.data.shipment.trackingEvents.length} tracking events on the first page (up to
+            20).
+          </p>
+          <ul>
+            {query.data.shipment.trackingEvents.map((event) => (
+              <li key={event.id}>
+                {event.eventType} · {new Date(event.timestamp).toLocaleString()}
+              </li>
+            ))}
+          </ul>
+        </>
+      )}
+    </section>
+  );
+}

package/src/operations/tracking-quality/quality.graphql

@@ -0,0 +1,15 @@
+query TrackingQualityIntegrations($pagination: PaginationInput!) {
+  integrations(pagination: $pagination) { id name provider status }
+}
+query TrackingQualityDeliveries($id: ID!, $pagination: PaginationInput!) {
+  integration(id: $id) {
+    id name provider status
+    events(pagination: $pagination) { id status receivedAt processedAt outcomes }
+  }
+}
+query TrackingQualityShipment($id: ID!) {
+  shipment(id: $id) {
+    id shipmentNumber status trackingNumber
+    trackingEvents(pagination: {limit: 20, offset: 0}) { id eventType timestamp }
+  }
+}