feat: add parts catalogs integration, catalog prefetch worker, and vehicle select modal

Integrate external parts catalogs API with auth service, add BullMQ-based
catalog prefetch worker for background data caching, expand vehicles service
with shared vehicle support, and add vehicle select modal to frontend.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/web/src/components/categories/category-grid.tsx

@@ -14,6 +14,7 @@ interface Category {
   schemaImageUrl?: string | null;
   parentId?: string | null;
   unavailable?: boolean;
+  source?: string;
 }
 
 interface CategoryGridProps {
@@ -46,7 +47,8 @@ export function CategoryGrid({ categories, vehicleId }: CategoryGridProps) {
       (c) =>
         c.children !== undefined &&
         c.children.length === 0 &&
-        !c.schemaImageUrl,
+        !c.schemaImageUrl &&
+        c.source !== "parts-catalogs",
     );
 
     if (leafsWithoutImage.length === 0) {

apps/web/src/components/categories/category-tree.tsx

@@ -14,6 +14,7 @@ interface Category {
   schemaImageUrl?: string | null;
   parentId?: string | null;
   unavailable?: boolean;
+  source?: string;
 }
 
 export function CategoryTree({ categories, vehicleId }: { categories: Category[]; vehicleId: string }) {
@@ -68,7 +69,7 @@ function CategoryNode({ category, vehicleId, level, parentPrefetching }: {
   useEffect(() => {
     if (!expanded || prefetchedRef.current) return;
     const leafs = children.filter(
-      (c) => c.children !== undefined && c.children.length === 0 && !c.schemaImageUrl,
+      (c) => c.children !== undefined && c.children.length === 0 && !c.schemaImageUrl && c.source !== "parts-catalogs",
     );
     if (leafs.length === 0) return;
     prefetchedRef.current = true;

apps/web/src/components/vehicles/vehicle-select-modal.tsx

@@ -0,0 +1,154 @@
+import { useState } from "react";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  Button,
+  Badge,
+  Separator,
+} from "@sase/ui";
+import { Car, Loader2, ChevronRight } from "lucide-react";
+
+interface PcatCandidate {
+  id: string;
+  name: string;
+  description?: string;
+  parameters?: Array<{ key: string; idx: string; value: string }>;
+  catalogId: string;
+}
+
+interface VehicleSelectModalProps {
+  open: boolean;
+  onClose: () => void;
+  candidates: PcatCandidate[];
+  vin: string;
+  onSelect: (carId: string) => void;
+  loading?: boolean;
+}
+
+export function VehicleSelectModal({
+  open,
+  onClose,
+  candidates,
+  vin,
+  onSelect,
+  loading,
+}: VehicleSelectModalProps) {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  function getParamValue(
+    params: PcatCandidate["parameters"],
+    keyword: string,
+  ): string | null {
+    if (!params) return null;
+    const p = params.find((param) =>
+      param.key.toLowerCase().includes(keyword),
+    );
+    return p?.value || null;
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={(v) => !v && onClose()}>
+      <DialogContent className="max-h-[85vh] overflow-y-auto sm:max-w-lg">
+        <DialogHeader>
+          <DialogTitle className="font-[family-name:var(--font-display)]">
+            Araç Seçimi
+          </DialogTitle>
+          <DialogDescription>
+            <span className="font-mono text-xs">{vin}</span> için birden fazla
+            araç bulundu. Lütfen aracınızı seçin.
+          </DialogDescription>
+        </DialogHeader>
+
+        <Separator className="my-2" />
+
+        <div className="space-y-2">
+          {candidates.map((car) => {
+            const year = getParamValue(car.parameters, "year");
+            const engine = getParamValue(car.parameters, "engine");
+            const body = getParamValue(car.parameters, "body");
+            const isSelected = selectedId === car.id;
+
+            return (
+              <button
+                key={car.id}
+                type="button"
+                onClick={() => setSelectedId(car.id)}
+                className={`group flex w-full items-center gap-4 rounded-xl border p-4 text-left transition-colors ${
+                  isSelected
+                    ? "border-primary bg-primary/5"
+                    : "border-border bg-background hover:bg-accent"
+                }`}
+              >
+                <div
+                  className={`flex size-10 shrink-0 items-center justify-center rounded-xl ${
+                    isSelected
+                      ? "bg-primary/10 text-primary"
+                      : "bg-muted text-muted-foreground"
+                  }`}
+                >
+                  <Car className="size-5" />
+                </div>
+                <div className="min-w-0 flex-1">
+                  <p className="truncate text-sm font-medium">{car.name}</p>
+                  {car.description && (
+                    <p className="truncate text-xs text-muted-foreground">
+                      {car.description}
+                    </p>
+                  )}
+                  <div className="mt-1.5 flex flex-wrap gap-1.5">
+                    {year && (
+                      <Badge variant="secondary" className="text-[10px]">
+                        {year}
+                      </Badge>
+                    )}
+                    {engine && (
+                      <Badge variant="secondary" className="text-[10px]">
+                        {engine}
+                      </Badge>
+                    )}
+                    {body && (
+                      <Badge variant="secondary" className="text-[10px]">
+                        {body}
+                      </Badge>
+                    )}
+                    <Badge variant="outline" className="text-[10px]">
+                      {car.catalogId}
+                    </Badge>
+                  </div>
+                </div>
+                <ChevronRight
+                  className={`size-4 shrink-0 transition-colors ${
+                    isSelected
+                      ? "text-primary"
+                      : "text-muted-foreground/50 group-hover:text-muted-foreground"
+                  }`}
+                />
+              </button>
+            );
+          })}
+        </div>
+
+        <Separator className="my-2" />
+
+        <div className="flex justify-end gap-2">
+          <Button variant="outline" onClick={onClose} className="rounded-xl">
+            Vazgeç
+          </Button>
+          <Button
+            disabled={!selectedId || loading}
+            onClick={() => selectedId && onSelect(selectedId)}
+            className="rounded-xl"
+          >
+            {loading ? (
+              <Loader2 className="mr-2 size-4 animate-spin" />
+            ) : null}
+            Seç ve Devam Et
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

apps/web/src/routes/dashboard/search.tsx

@@ -14,6 +14,7 @@ import { api, ApiError } from "@/lib/api-client";
 import { startAction } from "@/lib/faro";
 import { capture } from "@/lib/posthog";
 import { toast } from "@/lib/toast";
+import { VehicleSelectModal } from "@/components/vehicles/vehicle-select-modal";
 
 // ─── HELPERS ──────────────────────────────────────────────────────────────────
 
@@ -51,6 +52,11 @@ function SearchPage() {
   const [reportSending, setReportSending] = useState(false);
   const [reportSent, setReportSent] = useState(false);
 
+  // Vehicle candidate selection (PartsCatalogs multi-result)
+  const [candidates, setCandidates] = useState<any[] | null>(null);
+  const [candidateVin, setCandidateVin] = useState("");
+  const [selectLoading, setSelectLoading] = useState(false);
+
   // Live preview state
   const [preview, setPreview] = useState<{
     brandName: string;
@@ -142,6 +148,19 @@ function SearchPage() {
     setLoading(true);
     try {
       const data = await api.post<any>("/vehicles/decode", { vin: cleanVin });
+
+      // Handle multiple vehicle candidates (PartsCatalogs)
+      if (data.candidates && Array.isArray(data.candidates)) {
+        setCandidates(data.candidates);
+        setCandidateVin(cleanVin);
+        capture("vin_decode_candidates", {
+          vin: cleanVin,
+          count: data.candidates.length,
+        });
+        setLoading(false);
+        return;
+      }
+
       capture("vin_decode_success", { vin: cleanVin, vehicle_id: data.id });
       navigate({
         to: "/dashboard/vehicles/$id",
@@ -190,6 +209,36 @@ function SearchPage() {
     }
   }
 
+  async function handleCandidateSelect(pcatCarId: string) {
+    setSelectLoading(true);
+    try {
+      const data = await api.post<any>("/vehicles/decode", {
+        vin: candidateVin,
+        pcatCarId,
+      });
+      capture("vin_decode_candidate_selected", {
+        vin: candidateVin,
+        pcatCarId,
+        vehicle_id: data.id,
+      });
+      setCandidates(null);
+      navigate({
+        to: "/dashboard/vehicles/$id",
+        params: { id: data.id },
+      });
+    } catch (err) {
+      const message =
+        err instanceof ApiError
+          ? err.message
+          : "Bir hata oluştu. Lütfen tekrar deneyin.";
+      setError(message);
+      setCandidates(null);
+      toast.error("Araç seçimi başarısız");
+    } finally {
+      setSelectLoading(false);
+    }
+  }
+
   function fillExampleVin() {
     setVin("WVWZZZ1JZ3W597935");
     inputRef.current?.focus();
@@ -424,6 +473,18 @@ function SearchPage() {
           </p>
         </div>
       )}
+
+      {/* ─── Vehicle Selection Modal (PartsCatalogs multi-result) ──── */}
+      {candidates && (
+        <VehicleSelectModal
+          open={!!candidates}
+          onClose={() => setCandidates(null)}
+          candidates={candidates}
+          vin={candidateVin}
+          onSelect={handleCandidateSelect}
+          loading={selectLoading}
+        />
+      )}
     </div>
   );
 }