feat(berths): manual status catch-up wizard + reconciliation queue (#67)

Wires the long-dormant berths.status_override_mode column into a closed
loop so reps can reconcile berths flipped to under_offer/sold without a
backing interest.

Phase 1 — Status source tracking:
  - updateBerthStatus() stamps 'manual' on every user-facing write
  - berth-rules-engine.ts stamps 'automated' on auto-rule writes
  - new clearBerthOverride() helper nulls the field and stamps the
    reason "Reconciled via interest <id>" — only the wizard calls it

Phase 2 — Visual indicator:
  - Amber "Manual" chip on berth-list rows where statusOverrideMode='manual'
    AND no active linked interest (the candidates for catch-up)

Phase 3 — Reconciliation queue:
  - new service listManualReconcileBerths() with cross-port-safe
    NOT-EXISTS against activeInterestsWhere
  - GET /api/v1/berths/reconcile-queue
  - new page /[portSlug]/admin/berths/reconcile listing the queue,
    each row linking to the catch-up wizard

Phase 4 — Catch-up wizard:
  - POST /api/v1/berths/[id]/reconcile orchestrates create-client
    (optional quick-create), create-interest with primary berth link,
    and clearBerthOverride — composed via existing service helpers
  - <CatchUpWizard> dialog: existing-client or quick-create, optional
    yacht link, stage picker scoped to the current berth status, with
    contract auto-setting outcome=won

Phase 5 — Entry points:
  - sidebar Admin > "Reconcile berths" link
  - berth-list row action menu shows "Catch up…" on flagged rows

Doc upload + payment recording (spec phases 4.4 / 4.5) are deferred —
once the interest exists, the rep uses the standard interest detail
page surfaces for those follow-ups. The wizard's MVP responsibility is
to take a manual berth to "interest exists, override cleared" in one
round-trip.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/berths/berth-columns.tsx

@@ -1,7 +1,8 @@
 'use client';
 
+import { useState } from 'react';
 import { type ColumnDef } from '@tanstack/react-table';
-import { MoreHorizontal, Pencil, Activity } from 'lucide-react';
+import { MoreHorizontal, Pencil, Activity, RefreshCw } from 'lucide-react';
 import { useRouter, useParams } from 'next/navigation';
 
 import { Button } from '@/components/ui/button';
@@ -16,6 +17,7 @@ import { StatusPill, type StatusPillStatus } from '@/components/ui/status-pill';
 import { formatCurrency } from '@/lib/utils/currency';
 import { mooringLetterDot } from './mooring-letter-tone';
 import { stageBadgeClass, stageLabel } from '@/lib/constants';
+import { CatchUpWizard } from '@/components/berths/catch-up-wizard';
 
 export type BerthRow = {
   id: string;
@@ -66,6 +68,11 @@ export type BerthRow = {
   /** Most-advanced pipeline stage among the berth's active interests. Null
    *  when no active interest is linked. Read-only; computed server-side. */
   latestInterestStage?: string | null;
+  /** #67: source of the last status write. 'manual' when a human set it
+   *  via the API; 'automated' when a berth-rule fired; null on rows that
+   *  haven't been touched since seed. The reconciliation surface treats
+   *  'manual' + no latestInterestStage as a row needing catch-up. */
+  statusOverrideMode?: string | null;
 };
 
 /**
@@ -133,45 +140,84 @@ function StatusBadge({ status }: { status: string }) {
   );
 }
 
+/**
+ * #67 Phase 2: small amber chip beside the status pill flagging rows
+ * whose status was set manually and has no backing interest. These are
+ * the candidates for the catch-up wizard — the rep flipped a berth to
+ * "Under Offer" or "Sold" without ever creating the matching deal.
+ */
+function ManualBadge() {
+  return (
+    <span
+      className="inline-flex items-center rounded-full border border-amber-300 bg-amber-50 px-1.5 py-0.5 text-[10px] font-medium uppercase tracking-wide text-amber-800"
+      title="Status set manually with no backing interest — needs catch-up"
+    >
+      Manual
+    </span>
+  );
+}
+
 function ActionsCell({ row }: { row: { original: BerthRow } }) {
   const router = useRouter();
   const params = useParams<{ portSlug: string }>();
   const berth = row.original;
+  const [catchUpOpen, setCatchUpOpen] = useState(false);
+  const isManualUnreconciled = berth.statusOverrideMode === 'manual' && !berth.latestInterestStage;
 
   return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <Button
-          variant="ghost"
-          size="icon"
-          className="h-8 w-8"
-          onClick={(e) => e.stopPropagation()}
-        >
-          <MoreHorizontal className="h-4 w-4" aria-hidden />
-          <span className="sr-only">Open menu</span>
-        </Button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align="end">
-        <DropdownMenuItem
-          onClick={(e) => {
-            e.stopPropagation();
-            router.push(`/${params.portSlug}/berths/${berth.id}`);
-          }}
-        >
-          <Activity className="mr-2 h-4 w-4" aria-hidden />
-          View details
-        </DropdownMenuItem>
-        <DropdownMenuItem
-          onClick={(e) => {
-            e.stopPropagation();
-            router.push(`/${params.portSlug}/berths/${berth.id}?edit=true`);
-          }}
-        >
-          <Pencil className="mr-2 h-4 w-4" aria-hidden />
-          Edit
-        </DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-8 w-8"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <MoreHorizontal className="h-4 w-4" aria-hidden />
+            <span className="sr-only">Open menu</span>
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem
+            onClick={(e) => {
+              e.stopPropagation();
+              router.push(`/${params.portSlug}/berths/${berth.id}`);
+            }}
+          >
+            <Activity className="mr-2 h-4 w-4" aria-hidden />
+            View details
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={(e) => {
+              e.stopPropagation();
+              router.push(`/${params.portSlug}/berths/${berth.id}?edit=true`);
+            }}
+          >
+            <Pencil className="mr-2 h-4 w-4" aria-hidden />
+            Edit
+          </DropdownMenuItem>
+          {isManualUnreconciled ? (
+            <DropdownMenuItem
+              onClick={(e) => {
+                e.stopPropagation();
+                setCatchUpOpen(true);
+              }}
+            >
+              <RefreshCw className="mr-2 h-4 w-4" aria-hidden />
+              Catch up…
+            </DropdownMenuItem>
+          ) : null}
+        </DropdownMenuContent>
+      </DropdownMenu>
+      {isManualUnreconciled ? (
+        <CatchUpWizard
+          berthId={catchUpOpen ? berth.id : null}
+          open={catchUpOpen}
+          onOpenChange={setCatchUpOpen}
+        />
+      ) : null}
+    </>
   );
 }
 
@@ -208,7 +254,16 @@ export const berthColumns: ColumnDef<BerthRow, unknown>[] = [
     id: 'status',
     accessorKey: 'status',
     header: 'Status',
-    cell: ({ row }) => <StatusBadge status={row.original.status} />,
+    cell: ({ row }) => {
+      const r = row.original;
+      const isManualUnreconciled = r.statusOverrideMode === 'manual' && !r.latestInterestStage;
+      return (
+        <div className="inline-flex items-center gap-1.5">
+          <StatusBadge status={r.status} />
+          {isManualUnreconciled ? <ManualBadge /> : null}
+        </div>
+      );
+    },
   },
   {
     id: 'latestInterestStage',

src/components/berths/catch-up-wizard.tsx

@@ -0,0 +1,276 @@
+'use client';
+
+import { useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { useRouter, useParams } from 'next/navigation';
+import { Loader2 } from 'lucide-react';
+import { toast } from 'sonner';
+
+import { Button } from '@/components/ui/button';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { ClientPicker } from '@/components/shared/client-picker';
+import { YachtPicker } from '@/components/yachts/yacht-picker';
+import { apiFetch } from '@/lib/api/client';
+import { toastError } from '@/lib/api/toast-error';
+import { PIPELINE_STAGES, STAGE_LABELS } from '@/components/clients/pipeline-constants';
+
+interface CatchUpWizardProps {
+  berthId: string | null;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+type ClientMode = 'existing' | 'new';
+
+interface BerthSummary {
+  id: string;
+  mooringNumber: string;
+  status: string;
+}
+
+const STATUS_TO_STAGES: Record<string, readonly string[]> = {
+  under_offer: ['enquiry', 'qualified', 'nurturing', 'eoi', 'reservation'],
+  sold: ['contract'],
+  available: PIPELINE_STAGES,
+};
+
+/**
+ * #67 Phase 4: catch-up wizard for manually-statused berths.
+ *
+ * MVP scope (intentionally tight):
+ *   - Pick existing client OR quick-create with name + email/phone
+ *   - Optional yacht link
+ *   - Stage picker scoped to the current berth status (sold → contract+won,
+ *     under_offer → enquiry...reservation, available → any)
+ *
+ * Doc upload + payment recording (Phases 4.4 / 4.5 of the spec) are
+ * out of scope for the initial cut — once the interest exists, the rep
+ * has the standard interest detail page to upload contracts and record
+ * payments. The wizard's job is to get them from "manual berth, no
+ * interest" to "interest exists, override cleared" in one round-trip.
+ */
+export function CatchUpWizard({ berthId, open, onOpenChange }: CatchUpWizardProps) {
+  const router = useRouter();
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
+  const queryClient = useQueryClient();
+
+  const [clientMode, setClientMode] = useState<ClientMode>('existing');
+  const [clientId, setClientId] = useState<string | null>(null);
+  const [newClientName, setNewClientName] = useState('');
+  const [newClientEmail, setNewClientEmail] = useState('');
+  const [newClientPhone, setNewClientPhone] = useState('');
+  const [yachtId, setYachtId] = useState<string | null>(null);
+  const [pipelineStage, setPipelineStage] = useState<string>('enquiry');
+
+  // Fetch the berth so the wizard can scope the stage options to what
+  // makes sense for the current manual status. Disabled until open so
+  // closed-state hover/preview doesn't fire the request.
+  const { data: berth } = useQuery<{ data: BerthSummary }>({
+    queryKey: ['berth', berthId, 'catch-up-summary'],
+    queryFn: () => apiFetch(`/api/v1/berths/${berthId}`),
+    enabled: open && !!berthId,
+  });
+
+  const allowedStages = berth ? (STATUS_TO_STAGES[berth.data.status] ?? PIPELINE_STAGES) : [];
+  // Default the stage picker to the "right" default for each status —
+  // sold defaults to contract (and we auto-set outcome=won server-side),
+  // under_offer defaults to eoi since that's the most common pre-deal
+  // status that reps mark manually.
+  const defaultStage = berth?.data.status === 'sold' ? 'contract' : 'eoi';
+
+  // Keep selected stage in sync with the loaded berth's allowed set.
+  if (berth && pipelineStage !== defaultStage && !allowedStages.includes(pipelineStage)) {
+    setPipelineStage(defaultStage);
+  }
+
+  const submit = useMutation({
+    mutationFn: async () => {
+      if (!berthId) throw new Error('berthId missing');
+      const body: Record<string, unknown> = { pipelineStage };
+      if (clientMode === 'existing') {
+        if (!clientId) throw new Error('Pick a client to continue');
+        body.clientId = clientId;
+      } else {
+        if (!newClientName.trim()) throw new Error('Enter the client name');
+        body.newClient = {
+          fullName: newClientName.trim(),
+          email: newClientEmail.trim() || undefined,
+          phone: newClientPhone.trim() || undefined,
+        };
+      }
+      if (yachtId) body.yachtId = yachtId;
+      if (pipelineStage === 'contract') body.outcome = 'won';
+      return apiFetch<{ data: { interestId: string; clientId: string } }>(
+        `/api/v1/berths/${berthId}/reconcile`,
+        { method: 'POST', body },
+      );
+    },
+    onSuccess: (res) => {
+      toast.success('Berth reconciled — new interest created');
+      queryClient.invalidateQueries({ queryKey: ['berths'] });
+      queryClient.invalidateQueries({ queryKey: ['berths', 'reconcile-queue'] });
+      queryClient.invalidateQueries({ queryKey: ['interests'] });
+      onOpenChange(false);
+      if (portSlug && res.data.interestId) {
+        router.push(`/${portSlug}/interests/${res.data.interestId}` as never);
+      }
+    },
+    onError: (err) => toastError(err),
+  });
+
+  function reset() {
+    setClientMode('existing');
+    setClientId(null);
+    setNewClientName('');
+    setNewClientEmail('');
+    setNewClientPhone('');
+    setYachtId(null);
+    setPipelineStage('enquiry');
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(o) => {
+        if (submit.isPending) return;
+        if (!o) reset();
+        onOpenChange(o);
+      }}
+    >
+      <DialogContent className="sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle>Catch up berth {berth?.data.mooringNumber ?? ''}</DialogTitle>
+          <DialogDescription>
+            Create the backing interest so this berth drops out of the reconciliation queue. You can
+            attach documents and record payments from the new interest&apos;s detail page after
+            submission.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <Label>Client</Label>
+            <RadioGroup
+              value={clientMode}
+              onValueChange={(v) => setClientMode(v as ClientMode)}
+              className="flex gap-4"
+            >
+              <div className="flex items-center gap-2">
+                <RadioGroupItem id="cu-client-existing" value="existing" />
+                <Label htmlFor="cu-client-existing" className="text-sm font-normal">
+                  Pick existing
+                </Label>
+              </div>
+              <div className="flex items-center gap-2">
+                <RadioGroupItem id="cu-client-new" value="new" />
+                <Label htmlFor="cu-client-new" className="text-sm font-normal">
+                  Quick-create
+                </Label>
+              </div>
+            </RadioGroup>
+            {clientMode === 'existing' ? (
+              <ClientPicker value={clientId} onChange={setClientId} />
+            ) : (
+              <div className="space-y-2 rounded-md border bg-muted/30 p-3">
+                <div className="space-y-1">
+                  <Label className="text-xs">Full name *</Label>
+                  <Input
+                    value={newClientName}
+                    onChange={(e) => setNewClientName(e.target.value)}
+                    placeholder="John Smith"
+                  />
+                </div>
+                <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+                  <div className="space-y-1">
+                    <Label className="text-xs">Email</Label>
+                    <Input
+                      type="email"
+                      value={newClientEmail}
+                      onChange={(e) => setNewClientEmail(e.target.value)}
+                      placeholder="client@example.com"
+                    />
+                  </div>
+                  <div className="space-y-1">
+                    <Label className="text-xs">Phone</Label>
+                    <Input
+                      type="tel"
+                      value={newClientPhone}
+                      onChange={(e) => setNewClientPhone(e.target.value)}
+                      placeholder="+1 555 0100"
+                    />
+                  </div>
+                </div>
+              </div>
+            )}
+          </div>
+
+          <div className="space-y-1">
+            <Label>Linked yacht (optional)</Label>
+            <YachtPicker
+              value={yachtId}
+              onChange={setYachtId}
+              ownerFilter={
+                clientId && clientMode === 'existing' ? { type: 'client', id: clientId } : undefined
+              }
+            />
+          </div>
+
+          <div className="space-y-1">
+            <Label>Pipeline stage</Label>
+            <Select value={pipelineStage} onValueChange={setPipelineStage}>
+              <SelectTrigger>
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {allowedStages.map((s) => (
+                  <SelectItem key={s} value={s}>
+                    {STAGE_LABELS[s as keyof typeof STAGE_LABELS] ?? s}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+            {pipelineStage === 'contract' ? (
+              <p className="text-xs text-muted-foreground">
+                Stage <strong>Contract</strong> auto-marks the interest <strong>Won</strong> since
+                the berth is already flipped to Sold.
+              </p>
+            ) : null}
+          </div>
+        </div>
+
+        <DialogFooter>
+          <Button
+            type="button"
+            variant="outline"
+            onClick={() => onOpenChange(false)}
+            disabled={submit.isPending}
+          >
+            Cancel
+          </Button>
+          <Button type="button" onClick={() => submit.mutate()} disabled={submit.isPending}>
+            {submit.isPending && <Loader2 className="mr-1.5 size-3.5 animate-spin" aria-hidden />}
+            Create interest & clear manual flag
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}