feat(client-archive): smart-restore wizard with auto/opt-in/locked sections

Replaces the simple confirm-restore dialog with a wizard that reads the
persisted archive_metadata via /restore-dossier and surfaces:
- auto-reversed (e.g. berth still available → re-attached on restore)
- opt-in to undo (e.g. berth now under offer to another client)
- locked (e.g. yacht transferred and new owner has active interests)

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

src/components/clients/client-detail-header.tsx

@@ -1,19 +1,20 @@
 'use client';
 
+import { useRouter } from 'next/navigation';
 import { useState } from 'react';
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { Archive, Mail, MessageCircle, Phone, RotateCcw } from 'lucide-react';
+import { Archive, Mail, MessageCircle, Phone, RotateCcw, Trash2 } from 'lucide-react';
 import { format } from 'date-fns';
 
 import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
-import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
+import { PermissionGate } from '@/components/shared/permission-gate';
 import { SmartArchiveDialog } from '@/components/clients/smart-archive-dialog';
+import { SmartRestoreDialog } from '@/components/clients/smart-restore-dialog';
+import { HardDeleteDialog } from '@/components/clients/hard-delete-dialog';
 import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PortalInviteButton } from '@/components/clients/portal-invite-button';
 import { GdprExportButton } from '@/components/clients/gdpr-export-button';
-import { apiFetch } from '@/lib/api/client';
 import { cn } from '@/lib/utils';
 import { getCountryName } from '@/lib/i18n/countries';
 
@@ -37,20 +38,12 @@ interface ClientDetailHeaderProps {
 }
 
 export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
-  const queryClient = useQueryClient();
+  const router = useRouter();
   const [archiveOpen, setArchiveOpen] = useState(false);
+  const [hardDeleteOpen, setHardDeleteOpen] = useState(false);
 
   const isArchived = !!client.archivedAt;
 
-  const restoreMutation = useMutation({
-    mutationFn: () => apiFetch(`/api/v1/clients/${client.id}/restore`, { method: 'POST' }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['clients', client.id] });
-      queryClient.invalidateQueries({ queryKey: ['clients'] });
-      setArchiveOpen(false);
-    },
-  });
-
   const primaryEmail =
     client.contacts?.find((c) => c.channel === 'email' && c.isPrimary)?.value ??
     client.contacts?.find((c) => c.channel === 'email')?.value;
@@ -161,8 +154,23 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
             )}
           </div>
 
-          {/* Top-right: archive/restore as a small icon button - destructive
-              action sits out of the primary action flow. */}
+          {/* Top-right: archive/restore + (for archived clients with the
+              right perm) permanently-delete. Destructive actions sit out
+              of the primary action flow. */}
+          <div className="flex items-start gap-1">
+            {isArchived && (
+              <PermissionGate resource="admin" action="permanently_delete_clients">
+                <button
+                  type="button"
+                  onClick={() => setHardDeleteOpen(true)}
+                  aria-label="Permanently delete client"
+                  title="Permanently delete client"
+                  className="shrink-0 rounded-md p-1.5 text-muted-foreground/70 transition-colors hover:bg-destructive/10 hover:text-destructive"
+                >
+                  <Trash2 className="size-4" />
+                </button>
+              </PermissionGate>
+            )}
             <button
               type="button"
               onClick={() => setArchiveOpen(true)}
@@ -177,20 +185,15 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
               {isArchived ? <RotateCcw className="size-4" /> : <Archive className="size-4" />}
             </button>
           </div>
+        </div>
       </DetailHeaderStrip>
 
-      {/* Restore flow keeps the simple confirm dialog (the smart restore
-          wizard ships in a follow-on commit). Archive uses the new smart
-          dialog with the dossier + per-section decisions. */}
       {isArchived ? (
-        <ArchiveConfirmDialog
+        <SmartRestoreDialog
           open={archiveOpen}
           onOpenChange={setArchiveOpen}
-          entityName={client.fullName}
-          entityType="Client"
-          isArchived
-          onConfirm={() => restoreMutation.mutate()}
-          isLoading={restoreMutation.isPending}
+          clientId={client.id}
+          clientName={client.fullName}
         />
       ) : (
         <SmartArchiveDialog
@@ -200,6 +203,16 @@ export function ClientDetailHeader({ client }: ClientDetailHeaderProps) {
           clientName={client.fullName}
         />
       )}
+
+      {isArchived && (
+        <HardDeleteDialog
+          open={hardDeleteOpen}
+          onOpenChange={setHardDeleteOpen}
+          clientId={client.id}
+          clientName={client.fullName}
+          onDeleted={() => router.back()}
+        />
+      )}
     </>
   );
 }

src/components/clients/smart-restore-dialog.tsx

@@ -0,0 +1,245 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import {
+  AlertTriangle,
+  Anchor,
+  CheckCircle2,
+  FileText,
+  Loader2,
+  Lock,
+  Ship,
+  Wrench,
+} from 'lucide-react';
+import { toast } from 'sonner';
+
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { Checkbox } from '@/components/ui/checkbox';
+import { apiFetch } from '@/lib/api/client';
+
+interface RestoreReversal {
+  id: string;
+  kind: string;
+  refId: string;
+  label: string;
+  reason: string;
+}
+interface LockedReversal extends RestoreReversal {
+  lockReason: string;
+}
+interface RestoreDossier {
+  client: { id: string; fullName: string; portId: string };
+  autoReversible: RestoreReversal[];
+  reversibleWithPrompt: RestoreReversal[];
+  locked: LockedReversal[];
+}
+
+interface Props {
+  open: boolean;
+  onOpenChange: (next: boolean) => void;
+  clientId: string;
+  clientName: string;
+  onSuccess?: () => void;
+}
+
+function iconFor(kind: string) {
+  if (kind.startsWith('berth_')) return <Anchor className="h-3 w-3" />;
+  if (kind.startsWith('yacht_')) return <Ship className="h-3 w-3" />;
+  if (kind.startsWith('documenso_')) return <FileText className="h-3 w-3" />;
+  return <Wrench className="h-3 w-3" />;
+}
+
+export function SmartRestoreDialog({ open, onOpenChange, clientId, clientName, onSuccess }: Props) {
+  const qc = useQueryClient();
+
+  const dossierQuery = useQuery({
+    queryKey: ['client-restore-dossier', clientId],
+    queryFn: () =>
+      apiFetch<{ data: RestoreDossier }>(`/api/v1/clients/${clientId}/restore-dossier`),
+    enabled: open,
+  });
+
+  const dossier = dossierQuery.data?.data;
+
+  const [selected, setSelected] = useState<Record<string, boolean>>({});
+
+  useEffect(() => {
+    if (!open || !dossier) return;
+    setSelected({});
+  }, [open, dossier]);
+
+  const restoreMutation = useMutation({
+    mutationFn: () => {
+      const applyReversals = Object.entries(selected)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+      return apiFetch<{
+        data: { autoReversed: number; promptedReversed: number; lockedSkipped: number };
+      }>(`/api/v1/clients/${clientId}/restore`, {
+        method: 'POST',
+        body: { applyReversals },
+      });
+    },
+    onSuccess: (res) => {
+      const d = res.data;
+      const parts: string[] = [];
+      if (d.autoReversed > 0) parts.push(`${d.autoReversed} auto-reversed`);
+      if (d.promptedReversed > 0) parts.push(`${d.promptedReversed} re-applied`);
+      if (d.lockedSkipped > 0) parts.push(`${d.lockedSkipped} locked`);
+      toast.success(`${clientName} restored${parts.length > 0 ? ` (${parts.join(', ')})` : ''}.`);
+      qc.invalidateQueries({ queryKey: ['clients'] });
+      qc.invalidateQueries({ queryKey: ['clients', clientId] });
+      qc.invalidateQueries({ queryKey: ['berths'] });
+      qc.invalidateQueries({ queryKey: ['interests'] });
+      onOpenChange(false);
+      onSuccess?.();
+    },
+    onError: (err: unknown) => {
+      toast.error(err instanceof Error ? err.message : 'Restore failed');
+    },
+  });
+
+  const nothingToShow = useMemo(
+    () =>
+      !!dossier &&
+      dossier.autoReversible.length === 0 &&
+      dossier.reversibleWithPrompt.length === 0 &&
+      dossier.locked.length === 0,
+    [dossier],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-2xl">
+        <DialogHeader>
+          <DialogTitle>Restore {clientName}</DialogTitle>
+          <DialogDescription>
+            Review what was changed at archive time and decide which changes to undo. The client
+            record itself will always be un-archived.
+          </DialogDescription>
+        </DialogHeader>
+
+        {dossierQuery.isLoading ? (
+          <div className="py-8 text-center text-sm text-muted-foreground">
+            <Loader2 className="h-5 w-5 animate-spin mx-auto mb-2" />
+            Loading restore dossier…
+          </div>
+        ) : dossierQuery.error || !dossier ? (
+          <div className="py-8 text-center text-sm text-red-600">
+            Failed to load dossier:{' '}
+            {dossierQuery.error instanceof Error ? dossierQuery.error.message : 'unknown error'}
+          </div>
+        ) : nothingToShow ? (
+          <div className="py-6 text-center text-sm text-muted-foreground">
+            No tracked archive changes to review. The client will simply be un-archived.
+          </div>
+        ) : (
+          <div className="space-y-3 max-h-[60vh] overflow-y-auto pr-1">
+            {dossier.autoReversible.length > 0 && (
+              <Card className="border-emerald-300 bg-emerald-50">
+                <CardHeader className="pb-2">
+                  <CardTitle className="text-sm font-medium text-emerald-900 flex items-center gap-2">
+                    <CheckCircle2 className="h-4 w-4" /> Auto-reversed (
+                    {dossier.autoReversible.length})
+                  </CardTitle>
+                </CardHeader>
+                <CardContent className="text-xs space-y-1.5 text-emerald-900">
+                  {dossier.autoReversible.map((r) => (
+                    <div key={r.id} className="flex items-start gap-2">
+                      <span className="mt-0.5">{iconFor(r.kind)}</span>
+                      <span>
+                        <span className="font-medium">{r.label}</span> — {r.reason}
+                      </span>
+                    </div>
+                  ))}
+                </CardContent>
+              </Card>
+            )}
+
+            {dossier.reversibleWithPrompt.length > 0 && (
+              <Card className="border-amber-300 bg-amber-50">
+                <CardHeader className="pb-2">
+                  <CardTitle className="text-sm font-medium text-amber-900 flex items-center gap-2">
+                    <AlertTriangle className="h-4 w-4" /> Opt-in to undo (
+                    {dossier.reversibleWithPrompt.length})
+                  </CardTitle>
+                </CardHeader>
+                <CardContent className="text-xs space-y-2 text-amber-900">
+                  {dossier.reversibleWithPrompt.map((r) => (
+                    <label
+                      key={r.id}
+                      className="flex items-start gap-2 cursor-pointer rounded p-1 -mx-1 hover:bg-amber-100"
+                    >
+                      <Checkbox
+                        checked={!!selected[r.id]}
+                        onCheckedChange={(v) =>
+                          setSelected((prev) => ({ ...prev, [r.id]: v === true }))
+                        }
+                        className="mt-0.5"
+                      />
+                      <span className="flex-1">
+                        <span className="flex items-center gap-1.5 font-medium">
+                          {iconFor(r.kind)} {r.label}
+                        </span>
+                        <span className="text-xs">{r.reason}</span>
+                      </span>
+                    </label>
+                  ))}
+                </CardContent>
+              </Card>
+            )}
+
+            {dossier.locked.length > 0 && (
+              <Card className="border-slate-300 bg-slate-50">
+                <CardHeader className="pb-2">
+                  <CardTitle className="text-sm font-medium text-slate-900 flex items-center gap-2">
+                    <Lock className="h-4 w-4" /> Cannot be undone ({dossier.locked.length})
+                  </CardTitle>
+                </CardHeader>
+                <CardContent className="text-xs space-y-1.5 text-slate-700">
+                  {dossier.locked.map((r) => (
+                    <div key={r.id} className="flex items-start gap-2">
+                      <span className="mt-0.5">{iconFor(r.kind)}</span>
+                      <span>
+                        <span className="font-medium">{r.label}</span> — {r.reason}.{' '}
+                        <span className="italic">{r.lockReason}</span>
+                      </span>
+                    </div>
+                  ))}
+                </CardContent>
+              </Card>
+            )}
+          </div>
+        )}
+
+        <DialogFooter>
+          <Button variant="outline" onClick={() => onOpenChange(false)}>
+            Cancel
+          </Button>
+          <Button
+            onClick={() => restoreMutation.mutate()}
+            disabled={!dossier || restoreMutation.isPending}
+          >
+            {restoreMutation.isPending ? (
+              <>
+                <Loader2 className="h-4 w-4 animate-spin mr-1.5" /> Restoring…
+              </>
+            ) : (
+              'Restore client'
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}