@burdenoff/microfe-movethewheels 2026.1102.1 → 2026.1102.2

package/src/movethewheels/components/freight-invoice/InvoiceReviewPanel.tsx

@@ -0,0 +1,319 @@
+import { useState } from 'react';
+import { Button } from '../ui';
+import { FreightSelect } from '../freight-cost/FreightFields';
+import { ReuseState, reuseCard } from '../ReuseControls';
+import { useConditionApi, useConditionQuery } from '../../hooks/useContainerCondition';
+import {
+  DecideInvoiceReviewDocument,
+  HandOffInvoiceSettlementDocument,
+  InvoiceReviewExactDocument,
+  RecordInvoiceSupplierResponseDocument,
+  ResolveInvoiceDisputeDocument,
+  type InvoiceReceiptFragment,
+  type InvoiceReviewExactQuery,
+  type InvoiceReviewFragment,
+  type MtwFreightInvoiceDecision,
+  type MtwFreightInvoiceResolution,
+  type MtwFreightInvoiceReviewAction,
+} from '../../../generated/freight-invoice-operations';
+import { invoiceMoney } from '../../utils/invoiceComparison';
+import {
+  DRAFT_PROBLEM_LABELS,
+  REVIEW_EVENT_LABELS,
+  REVIEW_STATUS_LABELS,
+  authorNotice,
+  availableReviewActions,
+  decisionInput,
+  handOffInput,
+  isDraftProblem,
+  resolutionInput,
+  supplierResponseInput,
+  type ReviewPermissions,
+} from '../../utils/invoiceReview';
+
+const textArea = 'mt-1 min-h-24 w-full rounded border p-2';
+
+/**
+ * Review, dispute and Billing hand-off for one exact comparison revision
+ * (BOFF-10588). Every step appends to the revision's history; nothing is edited.
+ */
+export function InvoiceReviewPanel({
+  record,
+  permissions,
+  onChanged,
+}: {
+  record: Pick<InvoiceReceiptFragment, 'id' | 'shipmentId' | 'facts'>;
+  permissions: ReviewPermissions;
+  onChanged?: () => void;
+}) {
+  const [revision, setRevision] = useState(0);
+  const review = useConditionQuery<InvoiceReviewExactQuery>(
+    InvoiceReviewExactDocument,
+    permissions.canRead ? { shipmentId: record.shipmentId, comparisonId: record.id } : null,
+    revision
+  );
+  if (!permissions.canRead)
+    return (
+      <section className={reuseCard} aria-label="Invoice review">
+        <h2 className="text-lg font-semibold">Invoice review</h2>
+        <p>Freight invoice read permission is required to see the review status of this invoice.</p>
+      </section>
+    );
+  const value = review.data?.mtwFreightInvoiceReview;
+  return (
+    <section className={reuseCard} aria-label="Invoice review">
+      <h2 className="text-lg font-semibold">Invoice review</h2>
+      <ReuseState loading={review.loading} error={review.error} />
+      {value && (
+        <ReviewBody
+          key={`${value.comparisonId}:${value.sequence}`}
+          review={value}
+          lines={record.facts.rows}
+          permissions={permissions}
+          onRecorded={() => {
+            setRevision((n) => n + 1);
+            onChanged?.();
+          }}
+        />
+      )}
+    </section>
+  );
+}
+
+function ReviewBody({
+  review,
+  lines,
+  permissions,
+  onRecorded,
+}: {
+  review: InvoiceReviewFragment;
+  lines: InvoiceReceiptFragment['facts']['rows'];
+  permissions: ReviewPermissions;
+  onRecorded: () => void;
+}) {
+  const actions = availableReviewActions(review, permissions);
+  const notice = authorNotice(review);
+  const lineLabel = (id: string) => lines.find((line) => line.id === id)?.description ?? id;
+  return (
+    <div className="space-y-4">
+      <p className="font-medium" role="status">
+        Status: {REVIEW_STATUS_LABELS[review.status]}
+      </p>
+      <p>
+        Revision {review.revision} of {review.latestRevision}. Known invoice amount{' '}
+        {invoiceMoney(review.knownInvoiceAmountMinor, review.currency)}
+        {review.invoiceAmountComplete
+          ? ''
+          : ' (some reported amounts are unknown and are not counted as zero)'}
+        .
+      </p>
+      {review.status === 'SUPERSEDED' && (
+        <p>
+          A newer correction replaces this revision; review continues on the latest revision.
+          {review.resolvedByCorrection && ' Its open dispute was resolved by that correction.'}
+        </p>
+      )}
+      {review.settlementReference && (
+        <p>
+          Handed to platform Billing for settlement under reference{' '}
+          <span className="break-all font-mono">{review.settlementReference}</span>. This revision
+          can no longer be corrected.
+        </p>
+      )}
+      {notice && <p>{notice}</p>}
+      {review.events.length > 0 && (
+        <ol className="space-y-2" aria-label="Review history">
+          {review.events.map((event) => (
+            <li key={event.id} className="rounded border p-3 text-sm">
+              <p className="font-medium">
+                {event.sequence}. {REVIEW_EVENT_LABELS[event.kind]} —{' '}
+                {REVIEW_STATUS_LABELS[event.statusAfter]}
+              </p>
+              <p>
+                {event.recordedAt} by {event.createdBy}
+              </p>
+              {event.reason && <p className="whitespace-pre-wrap break-words">{event.reason}</p>}
+              {event.disputedLineIds.length > 0 && (
+                <p>Disputed lines: {event.disputedLineIds.map(lineLabel).join(', ')}</p>
+              )}
+            </li>
+          ))}
+        </ol>
+      )}
+      {actions.length > 0 ? (
+        <ReviewStep review={review} actions={actions} lines={lines} onRecorded={onRecorded} />
+      ) : (
+        review.status !== 'SUPERSEDED' &&
+        review.status !== 'SETTLEMENT_HANDED_OFF' &&
+        !notice && <p>Your role cannot take the next review step on this invoice.</p>
+      )}
+    </div>
+  );
+}
+
+const ACTION_LABELS: Record<MtwFreightInvoiceReviewAction, string> = {
+  DECIDE: 'Accept or dispute',
+  RECORD_SUPPLIER_RESPONSE: 'Record supplier response',
+  RESOLVE_DISPUTE: 'Resolve dispute',
+  HAND_OFF_SETTLEMENT: 'Hand off to Billing',
+};
+
+function ReviewStep({
+  review,
+  actions,
+  lines,
+  onRecorded,
+}: {
+  review: InvoiceReviewFragment;
+  actions: MtwFreightInvoiceReviewAction[];
+  lines: InvoiceReceiptFragment['facts']['rows'];
+  onRecorded: () => void;
+}) {
+  const request = useConditionApi();
+  const [action, setAction] = useState<MtwFreightInvoiceReviewAction>(actions[0]);
+  const [decision, setDecision] = useState<MtwFreightInvoiceDecision>('ACCEPTED');
+  const [resolution, setResolution] = useState<MtwFreightInvoiceResolution>('ACCEPTED');
+  const [reason, setReason] = useState('');
+  const [disputed, setDisputed] = useState<string[]>([]);
+  // One key per draft: a resend after a lost response replays instead of recording twice.
+  const [idempotencyKey, setKey] = useState(() => crypto.randomUUID());
+  const [busy, setBusy] = useState(false);
+  const [problem, setProblem] = useState<string | null>(null);
+  const edit =
+    <T,>(set: (value: T) => void) =>
+    (value: T) => {
+      set(value);
+      setKey(crypto.randomUUID());
+      setProblem(null);
+    };
+  const base = { review, idempotencyKey };
+  const submit = async () => {
+    const plan =
+      action === 'DECIDE'
+        ? {
+            document: DecideInvoiceReviewDocument,
+            input: decisionInput(base, decision, reason, disputed),
+          }
+        : action === 'RECORD_SUPPLIER_RESPONSE'
+          ? {
+              document: RecordInvoiceSupplierResponseDocument,
+              input: supplierResponseInput(base, reason),
+            }
+          : action === 'RESOLVE_DISPUTE'
+            ? {
+                document: ResolveInvoiceDisputeDocument,
+                input: resolutionInput(base, resolution, reason),
+              }
+            : { document: HandOffInvoiceSettlementDocument, input: handOffInput(base, reason) };
+    if (isDraftProblem(plan.input)) {
+      setProblem(DRAFT_PROBLEM_LABELS[plan.input]);
+      return;
+    }
+    setBusy(true);
+    setProblem(null);
+    try {
+      await request(plan.document, { input: plan.input });
+      onRecorded();
+    } catch (failure) {
+      setProblem(failure instanceof Error ? failure.message : 'The review step was not recorded.');
+    } finally {
+      setBusy(false);
+    }
+  };
+  return (
+    <form
+      className="space-y-3 border-t pt-4"
+      aria-label="Next review step"
+      onSubmit={(event) => {
+        event.preventDefault();
+        void submit();
+      }}
+    >
+      {actions.length > 1 && (
+        <FreightSelect
+          label="Review step"
+          value={action}
+          onChange={(value) => edit(setAction)(value as MtwFreightInvoiceReviewAction)}
+        >
+          {actions.map((item) => (
+            <option key={item} value={item}>
+              {ACTION_LABELS[item]}
+            </option>
+          ))}
+        </FreightSelect>
+      )}
+      {action === 'DECIDE' && (
+        <>
+          <FreightSelect
+            label="Decision"
+            value={decision}
+            onChange={(value) => edit(setDecision)(value as MtwFreightInvoiceDecision)}
+          >
+            <option value="ACCEPTED">Accept</option>
+            <option value="ACCEPTED_WITH_VARIANCE">Accept with variance</option>
+            <option value="DISPUTED">Dispute</option>
+          </FreightSelect>
+          {decision === 'DISPUTED' && (
+            <fieldset className="space-y-2">
+              <legend className="text-sm font-medium">Disputed invoice lines</legend>
+              {lines.map((line) => (
+                <label key={line.id} className="flex min-h-11 items-center gap-2 text-sm">
+                  <input
+                    type="checkbox"
+                    checked={disputed.includes(line.id)}
+                    onChange={(event) =>
+                      edit(setDisputed)(
+                        event.target.checked
+                          ? [...disputed, line.id]
+                          : disputed.filter((id) => id !== line.id)
+                      )
+                    }
+                  />
+                  {line.description} ({invoiceMoney(line.amountMinor, line.currency)})
+                </label>
+              ))}
+            </fieldset>
+          )}
+        </>
+      )}
+      {action === 'RESOLVE_DISPUTE' && (
+        <FreightSelect
+          label="Resolution"
+          value={resolution}
+          onChange={(value) => edit(setResolution)(value as MtwFreightInvoiceResolution)}
+        >
+          <option value="ACCEPTED">Accept as invoiced</option>
+          <option value="ACCEPTED_WITH_VARIANCE">Accept with variance</option>
+        </FreightSelect>
+      )}
+      <label className="block text-sm">
+        {action === 'RECORD_SUPPLIER_RESPONSE'
+          ? "Supplier's response"
+          : action === 'HAND_OFF_SETTLEMENT'
+            ? 'Note for Billing (optional)'
+            : 'Reason'}
+        <textarea
+          className={textArea}
+          value={reason}
+          maxLength={1000}
+          onChange={(event) => edit(setReason)(event.target.value)}
+        />
+      </label>
+      {action === 'RESOLVE_DISPUTE' && (
+        <p className="text-sm">
+          A dispute can also close by recording a corrected invoice revision.
+        </p>
+      )}
+      {action === 'HAND_OFF_SETTLEMENT' && (
+        <p className="text-sm">
+          Billing settles the invoice; MoveTheWheels keeps no payment ledger. After hand-off this
+          revision can no longer be corrected.
+        </p>
+      )}
+      {problem && <p role="alert">{problem}</p>}
+      <Button type="submit" disabled={busy}>
+        {busy ? 'Recording…' : ACTION_LABELS[action]}
+      </Button>
+    </form>
+  );
+}

package/src/movethewheels/components/freight-invoice/InvoiceReviewQueue.tsx

@@ -0,0 +1,96 @@
+import { useState } from 'react';
+import { Button } from '../ui';
+import { FreightSelect } from '../freight-cost/FreightFields';
+import { ReusePager, ReuseState, reuseCard } from '../ReuseControls';
+import { useConditionQuery } from '../../hooks/useContainerCondition';
+import {
+  InvoiceReviewQueueDocument,
+  InvoiceReviewSummaryDocument,
+  type InvoiceReviewFragment,
+  type InvoiceReviewQueueQuery,
+  type InvoiceReviewSummaryQuery,
+  type MtwFreightInvoiceReviewStatus,
+} from '../../../generated/freight-invoice-operations';
+import { invoiceMoney } from '../../utils/invoiceComparison';
+import { REVIEW_QUEUE_STATUSES, REVIEW_STATUS_LABELS } from '../../utils/invoiceReview';
+
+const PAGE = 10;
+
+/** The latest revision of every recorded carrier invoice, filtered by review status (BOFF-10588). */
+export function InvoiceReviewQueue({
+  revision,
+  onOpen,
+  locked = false,
+}: {
+  revision: number;
+  onOpen: (review: InvoiceReviewFragment) => void;
+  /** True while an invoice or correction draft is open: opening a review would discard it. */
+  locked?: boolean;
+}) {
+  const [status, setStatus] = useState<MtwFreightInvoiceReviewStatus | ''>('AWAITING_REVIEW');
+  const [offset, setOffset] = useState(0);
+  const queue = useConditionQuery<InvoiceReviewQueueQuery>(
+    InvoiceReviewQueueDocument,
+    { status: status || null, pagination: { limit: PAGE, offset } },
+    revision
+  );
+  const page = queue.data?.mtwFreightInvoiceReviewPage;
+  return (
+    <section className={reuseCard} aria-label="Invoice review queue">
+      <h2 className="text-lg font-semibold">Invoice review queue</h2>
+      <p>The latest revision of each recorded carrier invoice. Open one to review it.</p>
+      {locked && (
+        <p role="status">Finish or cancel the invoice draft below before opening a review.</p>
+      )}
+      <FreightSelect
+        label="Review status"
+        value={status}
+        onChange={(value) => {
+          setStatus(value as MtwFreightInvoiceReviewStatus | '');
+          setOffset(0);
+        }}
+      >
+        <option value="">All statuses</option>
+        {REVIEW_QUEUE_STATUSES.map((item) => (
+          <option key={item} value={item}>
+            {REVIEW_STATUS_LABELS[item]}
+          </option>
+        ))}
+      </FreightSelect>
+      <ReuseState loading={queue.loading} error={queue.error} />
+      {page && page.items.length === 0 && <p>No invoices with this review status.</p>}
+      <ul className="space-y-2">
+        {page?.items.map((item) => (
+          <li key={item.comparisonId}>
+            <Button
+              type="button"
+              variant="outline"
+              className="h-auto w-full max-w-full justify-start whitespace-normal break-words text-left"
+              disabled={locked}
+              onClick={() => onOpen(item)}
+            >
+              {item.supplierLabel ?? item.supplierReference} / invoice {item.invoiceReference},
+              revision {item.revision} — {REVIEW_STATUS_LABELS[item.status]} —{' '}
+              {invoiceMoney(item.knownInvoiceAmountMinor, item.currency)}
+              {item.invoiceAmountComplete ? '' : ' known'}
+            </Button>
+          </li>
+        ))}
+      </ul>
+      <ReusePager page={page} busy={queue.loading} offset={offset} onChange={setOffset} />
+    </section>
+  );
+}
+
+/** Review counts over the latest revision of every recorded carrier invoice. */
+export function useInvoiceReviewSummary(enabled: boolean) {
+  const summary = useConditionQuery<InvoiceReviewSummaryQuery>(
+    InvoiceReviewSummaryDocument,
+    enabled ? {} : null
+  );
+  return {
+    summary: summary.data?.mtwFreightInvoiceReviewSummary ?? null,
+    loading: summary.loading,
+    error: summary.error,
+  };
+}

package/src/movethewheels/hooks/useInvoiceReviewPermissions.ts

@@ -0,0 +1,25 @@
+import { usePermissions } from '@burdenoff/fe-libs/shared/providers/shell';
+import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
+import type { ReviewPermissions } from '../utils/invoiceReview';
+
+/** Freight invoice review grants for this page's current actor and workspace (BOFF-10588). */
+export function useInvoiceReviewPermissions(): ReviewPermissions & { loading: boolean } {
+  const permissions = usePermissions();
+  const { workspaceId, currentUser } = useMoveTheWheels();
+  const currentScope = Boolean(
+    workspaceId &&
+    currentUser?.id &&
+    permissions.scopeId === workspaceId &&
+    (permissions.isSuperAdmin ||
+      (permissions.permissions?.scopeId === workspaceId &&
+        permissions.permissions.actorId === currentUser.id))
+  );
+  const ready = currentScope && !permissions.isLoading && !permissions.error;
+  const canRead = ready && permissions.hasPermission('mtw-freight-invoice:read');
+  return {
+    canRead,
+    canUpdate: canRead && permissions.hasPermission('mtw-freight-invoice:update'),
+    canApprove: canRead && permissions.hasPermission('mtw-freight-invoice:approve'),
+    loading: permissions.isLoading,
+  };
+}

package/src/movethewheels/pages/FinancePage.tsx

@@ -7,7 +7,9 @@
  * settlement are handled by the platform Billing module, which this page
  * deep-links to rather than re-implementing an Invoice ledger here. Carrier
  * invoices are checked against the agreed freight estimate on the freight
- * invoice comparison page, which this page links to (BOFF-4395).
+ * invoice comparison page, which this page links to (BOFF-4395). The review
+ * counts (awaiting review, disputed, accepted, handed to Billing) come from
+ * Query.mtwFreightInvoiceReviewSummary over real recorded invoices (BOFF-10588).
  */
 
 import { useMemo } from 'react';
@@ -30,6 +32,34 @@ import { useAnalytics, useFinanceMetrics } from '../hooks/useAnalytics';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { formatCurrency } from '../utils/formatters';
 import { joinPath } from '../utils/navigation';
+import { useInvoiceReviewSummary } from '../components/freight-invoice/InvoiceReviewQueue';
+
+function InvoiceReviewCounts() {
+  const { summary, loading, error } = useInvoiceReviewSummary(true);
+  if (loading) return <p className="text-sm text-text-secondary">Loading invoice review counts…</p>;
+  if (error || !summary)
+    return (
+      <p className="text-sm text-text-secondary">
+        Invoice review counts need freight invoice read permission.
+      </p>
+    );
+  const counts = [
+    { label: 'Awaiting review', value: summary.awaitingReview },
+    { label: 'Disputed', value: summary.disputed + summary.supplierResponded },
+    { label: 'Accepted', value: summary.accepted + summary.acceptedWithVariance },
+    { label: 'Handed to Billing', value: summary.settlementHandedOff },
+  ];
+  return (
+    <dl className="grid grid-cols-2 gap-2" aria-label="Carrier invoice review">
+      {counts.map((count) => (
+        <div key={count.label} className="rounded-lg border border-border-default p-3">
+          <dt className="text-xs text-text-secondary">{count.label}</dt>
+          <dd className="text-lg font-semibold text-text-primary">{count.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
 
 export default function FinancePage() {
   const { analytics } = useAnalytics();
@@ -156,8 +186,10 @@ export default function FinancePage() {
             <h3 className="text-sm font-semibold text-text-primary">Freight cost control</h3>
             <p className="text-sm text-text-secondary">
               Record the agreed freight estimate for a shipment, then check the carrier&apos;s
-              invoice against it line by line before it is settled in Billing.
+              invoice against it line by line. Someone other than its author accepts or disputes it,
+              and accepted invoices are handed to Billing for settlement.
             </p>
+            <InvoiceReviewCounts />
             <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
               <Button variant="outline" onClick={openFreightEstimates}>
                 <Receipt size={16} /> Freight estimates

package/src/movethewheels/pages/FreightInvoicePage.tsx

@@ -8,6 +8,9 @@ import { PinnedSelect, ReusePager, ReuseState, reuseCard } from '../components/R
 import { FreightText } from '../components/freight-cost/FreightFields';
 import { InvoiceForm } from '../components/freight-invoice/InvoiceForm';
 import { InvoiceHistoryRecord } from '../components/freight-invoice/InvoiceResults';
+import { InvoiceReviewPanel } from '../components/freight-invoice/InvoiceReviewPanel';
+import { InvoiceReviewQueue } from '../components/freight-invoice/InvoiceReviewQueue';
+import { useInvoiceReviewPermissions } from '../hooks/useInvoiceReviewPermissions';
 import { useMoveTheWheels } from '../providers/MoveTheWheelsProvider';
 import { useShipmentPermissions } from '../hooks/useShipmentPermissions';
 import { useConditionApi, useConditionQuery } from '../hooks/useContainerCondition';
@@ -29,6 +32,7 @@ import {
   type InvoiceComparisonExactQuery,
   type InvoiceReceiptFragment,
   type InvoiceStructuralPreviewQuery,
+  type InvoiceReviewFragment,
 } from '../../generated/freight-invoice-operations';
 import {
   sameInvoiceScope,
@@ -83,6 +87,8 @@ function InvoiceWorkbench({
   actions: ReturnType<typeof useInvoiceComparisonRecovery>;
 }) {
   const request = useConditionApi(),
+    reviewAccess = useInvoiceReviewPermissions(),
+    [reviewRevision, setReviewRevision] = useState(0),
     [params, setParams] = useSearchParams();
   const [shipment, setShipment] = useState(
       () => params.get('invoiceShipment')?.slice(0, 255) ?? ''
@@ -155,6 +161,27 @@ function InvoiceWorkbench({
       { replace: true }
     );
   };
+  const openReview = (row: InvoiceReviewFragment) => {
+    setShipment(row.shipmentId);
+    setEstimateId('');
+    setEstimateOffset(0);
+    setKnown(null);
+    setSelectedId(row.comparisonId);
+    setIdentity(row.invoiceIdentityId);
+    setIdentityEntry(row.invoiceIdentityId);
+    setHistoryOffset(0);
+    setStarted(false);
+    setCorrection(null);
+    setParams(
+      (previous) => {
+        const next = new URLSearchParams(previous);
+        next.set('invoiceShipment', row.shipmentId);
+        next.set('invoiceIdentity', row.invoiceIdentityId);
+        return next;
+      },
+      { replace: true }
+    );
+  };
   const options =
     shipments.data?.shipments.map((s) => ({
       id: s.id,
@@ -175,9 +202,10 @@ function InvoiceWorkbench({
   return (
     <div className="min-w-0 space-y-6 break-words">
       <p className="rounded border p-4 text-sm">
-        Record only what the supplier source reports. Unknown is not zero. This comparison
-        establishes no quote acceptance, liability, invoice approval or payment. Corrections append
-        a new immutable revision.
+        Record only what the supplier source reports. Unknown is not zero. Recording a comparison
+        does not approve it: someone other than its author accepts or disputes each revision, and
+        only an accepted invoice is handed to Billing for settlement. Corrections append a new
+        immutable revision.
       </p>
       {actions.uncertain && (
         <InvoiceRequestRecovery
@@ -197,6 +225,13 @@ function InvoiceWorkbench({
       )}
       {enabled && (
         <>
+          {reviewAccess.canRead && (
+            <InvoiceReviewQueue
+              revision={reviewRevision + actions.revision}
+              onOpen={openReview}
+              locked={paused || started}
+            />
+          )}
           <section className={reuseCard}>
             <h2 className="text-lg font-semibold">Choose the exact recorded estimate</h2>
             <PinnedSelect
@@ -401,6 +436,12 @@ function InvoiceWorkbench({
           {record && record.shipmentId === shipment && (
             <>
               <InvoiceHistoryRecord record={record} />
+              <InvoiceReviewPanel
+                key={`${record.id}:${actions.revision}`}
+                record={record}
+                permissions={reviewAccess}
+                onChanged={() => setReviewRevision((n) => n + 1)}
+              />
               <Button
                 type="button"
                 disabled={