@burdenoff/microfe-movethewheels 2026.1010.2 → 2026.1011.2

package/src/movethewheels/pages/TrackingEventQualityPage.tsx

@@ -0,0 +1,250 @@
+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 === 'ACCEPTED' || outcome.status === 'DUPLICATE') && (
+                          <p>
+                            Status decision:{' '}
+                            {outcome.projection?.status === 'APPLIED'
+                              ? 'Applied to the recorded shipment status'
+                              : outcome.projection?.status === 'HELD'
+                                ? `Held — ${outcome.projection.heldReason?.replaceAll('_', ' ').toLowerCase()}`
+                                : 'No status decision recorded in this legacy result'}
+                          </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. The chosen-source
+        clock policy and manual corrections control recorded shipment status. Provider corrections
+        and replay need separate reviewed 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/movethewheels/utils/shipmentStatusDraft.ts

@@ -0,0 +1,118 @@
+export interface ShipmentSourceDraft {
+  integrationId: string;
+  basisTrackingEventId: string;
+  maxSourceAgeSeconds: string;
+  maxFutureSkewSeconds: string;
+  reason: string;
+}
+
+export function statusDecisionReason(value: string): string {
+  const reason = value.trim();
+  if (!reason || reason.length > 1000) throw new Error('Enter a reason of 1–1000 characters.');
+  return reason;
+}
+
+function explicitSeconds(value: string, minimum: number, maximum: number, label: string): number {
+  if (!/^\d+$/.test(value.trim()))
+    throw new Error(`${label} must be an explicit whole number of seconds.`);
+  const result = Number(value.trim());
+  if (!Number.isSafeInteger(result) || result < minimum || result > maximum)
+    throw new Error(`${label} must be between ${minimum} and ${maximum} seconds.`);
+  return result;
+}
+
+export function shipmentSourceInput(draft: ShipmentSourceDraft, expectedStatusRevision: number) {
+  if (!draft.integrationId || !draft.basisTrackingEventId)
+    throw new Error('Choose one integration and one recorded basis event.');
+  return {
+    expectedStatusRevision,
+    integrationId: draft.integrationId,
+    basisTrackingEventId: draft.basisTrackingEventId,
+    maxSourceAgeSeconds: explicitSeconds(
+      draft.maxSourceAgeSeconds,
+      1,
+      2592000,
+      'Maximum source age'
+    ),
+    maxFutureSkewSeconds: explicitSeconds(
+      draft.maxFutureSkewSeconds,
+      0,
+      86400,
+      'Allowed future skew'
+    ),
+    reason: statusDecisionReason(draft.reason),
+  };
+}
+
+interface StatusAcknowledgement {
+  id: string;
+  status: string;
+  statusRevision: number;
+  statusAuthority: string;
+  statusAuthorityEpoch: number;
+  designatedIntegrationId?: string | null;
+  statusBasisEventId?: string | null;
+  statusBasisSourceTime?: string | null;
+  maxSourceAgeSeconds?: number | null;
+  maxFutureSkewSeconds?: number | null;
+}
+
+export function sourceStatusAcknowledged(
+  actual: StatusAcknowledgement | null | undefined,
+  expected: {
+    id: string;
+    epoch: number;
+    input: ReturnType<typeof shipmentSourceInput>;
+    basis: { id: string; eventType: string; providerEventTime?: string | null } | undefined;
+  }
+): boolean {
+  const statuses: Record<string, string> = {
+    PICKED_UP: 'PICKED_UP',
+    IN_TRANSIT: 'IN_TRANSIT',
+    ARRIVED: 'IN_TRANSIT',
+    DEPARTED: 'IN_TRANSIT',
+    OUT_FOR_DELIVERY: 'IN_TRANSIT',
+    DELIVERED: 'DELIVERED',
+    FAILED: 'FAILED',
+    RETURNED: 'RETURNED',
+  };
+  const basis = expected.basis;
+  const time = basis?.providerEventTime ? Date.parse(basis.providerEventTime) : NaN;
+  return (
+    !!actual &&
+    !!basis &&
+    Number.isFinite(time) &&
+    actual.id === expected.id &&
+    actual.statusRevision === expected.input.expectedStatusRevision + 1 &&
+    actual.statusAuthority === 'INTEGRATION_EVENT_TIME' &&
+    actual.statusAuthorityEpoch === expected.epoch + 1 &&
+    actual.designatedIntegrationId === expected.input.integrationId &&
+    actual.statusBasisEventId === basis.id &&
+    basis.id === expected.input.basisTrackingEventId &&
+    typeof actual.statusBasisSourceTime === 'string' &&
+    Date.parse(actual.statusBasisSourceTime) === time &&
+    actual.maxSourceAgeSeconds === expected.input.maxSourceAgeSeconds &&
+    actual.maxFutureSkewSeconds === expected.input.maxFutureSkewSeconds &&
+    typeof statuses[basis.eventType] === 'string' &&
+    actual.status === statuses[basis.eventType]
+  );
+}
+
+export function manualStatusAcknowledged(
+  actual: StatusAcknowledgement | null | undefined,
+  expected: { id: string; revision: number; epoch: number; status: string }
+): boolean {
+  return (
+    !!actual &&
+    actual.id === expected.id &&
+    actual.statusRevision === expected.revision + 1 &&
+    actual.status === expected.status &&
+    actual.statusAuthority === 'MANUAL_HOLD' &&
+    actual.statusAuthorityEpoch === expected.epoch + 1 &&
+    actual.designatedIntegrationId === null &&
+    actual.statusBasisEventId === null &&
+    actual.statusBasisSourceTime === null &&
+    actual.maxSourceAgeSeconds === null &&
+    actual.maxFutureSkewSeconds === null
+  );
+}

package/src/operations/shipment-status-authority/status.graphql

@@ -0,0 +1,80 @@
+fragment ShipmentStatusAuthorityFields on MtwShipment {
+  id
+  shipmentNumber
+  status
+  statusRevision
+  statusAuthority
+  statusAuthorityEpoch
+  designatedIntegrationId
+  statusBasisEventId
+  statusBasisSourceTime
+  maxSourceAgeSeconds
+  maxFutureSkewSeconds
+}
+
+query StatusAuthorityShipments($filter: ShipmentFilterInput, $pagination: PaginationInput!) {
+  shipments(filter: $filter, pagination: $pagination) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+query StatusAuthorityDetail($id: ID!, $pagination: PaginationInput!, $evidencePagination: PaginationInput!) {
+  shipment(id: $id) {
+    ...ShipmentStatusAuthorityFields
+    trackingEvents(pagination: $evidencePagination) {
+      id
+      eventType
+      sourceIntegrationId
+      sourceTimestampProvenance
+      providerEventTime
+      serverReceivedAt
+      timestamp
+    }
+  }
+  shipmentStatusDecisions(shipmentId: $id, pagination: $pagination) {
+    id
+    origin
+    outcome
+    heldReason
+    observedRevision
+    resultRevision
+    priorStatus
+    resultStatus
+    trackingEventId
+    proofId
+    reason
+    recordedAt
+    configuredIntegrationId
+    configuredMaxSourceAgeSeconds
+    configuredMaxFutureSkewSeconds
+  }
+}
+
+query StatusAuthoritySources($pagination: PaginationInput!) {
+  integrations(pagination: $pagination) {
+    id
+    name
+    provider
+    status
+  }
+}
+
+mutation StatusAuthorityConfigure($id: ID!, $input: ConfigureShipmentStatusSourceInput!) {
+  configureShipmentStatusSource(id: $id, input: $input) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+mutation StatusAuthorityManual($id: ID!, $input: UpdateShipmentInput!) {
+  updateShipment(id: $id, input: $input) {
+    ...ShipmentStatusAuthorityFields
+  }
+}
+
+query StatusAuthorityOwnedDelivery($deliveryJobId: ID!) {
+  myEpodShipmentStatus(deliveryJobId: $deliveryJobId) {
+    id
+    status
+    statusRevision
+  }
+}

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