feat(listings): AI advisor on listing detail — valuation + qualitative advice

New endpoint POST /analytics/listings/:id/ai-advice (JwtAuthGuard).
Orchestrates a single-listing AI analysis in Vietnamese via Anthropic
Claude, using the key/URL/model configured in admin settings.

Backend
-------
- New CQRS: get-listing-ai-advice/{query,handler}.ts under analytics.
  Injects LISTING_REPOSITORY, QueryBus (for nearby POIs + neighborhood
  score), SystemSettingsService (from @modules/admin), LoggerService.
- Controller @Post('listings/:id/ai-advice') in analytics.controller.ts.
- analytics.module.ts now imports ListingsModule + AdminModule.
- Anthropic call: native fetch to ${apiUrl}/messages with
  x-api-key + anthropic-version: 2023-06-01 +
  anthropic-beta: prompt-caching-2024-07-31. System block marked
  cache_control:{type:'ephemeral'} for cheap subsequent cache hits.
  30s AbortController timeout.
- Response validation without adding zod to the API workspace —
  lightweight isRecord/asInt/asString/asStringArray helpers.
  Strips ```json fences before JSON.parse.
- Error handling:
  * 503 AI_NOT_CONFIGURED when the admin hasn't saved an API key.
  * 502 AI_PROVIDER_ERROR on non-2xx, parse failure, or timeout.
  * Key never logged.
  * POI / score fetch failures are soft — prompt is built without
    them and the model still runs.
- New error codes AI_NOT_CONFIGURED / AI_PROVIDER_ERROR in
  shared/domain/error-codes.ts.

Response shape (returned unchanged to the client):
```
{
  valuation: { estimateVND, lowVND, highVND, confidence, rationale },
  advice: { summary, pros[], cons[], suitableFor[] },
  model, cacheHit
}
```

Frontend
--------
- analytics-api.ts: exports AiConfidence, ListingAiValuation,
  ListingAiAdviceBody, ListingAiAdvice + getListingAiAdvice(id).
- New components/listings/ai-advice-cards.tsx.
  * Default state: outline <Button><Sparkles/> Xem phân tích AI</Button>
  * On click: useMutation fires + skeleton with Sparkles spinner.
  * On success: two sidebar cards:
    - "AI định giá" — big mid VND, low–high range, Low/Medium/High
      confidence badge, rationale with line-clamp-3.
    - "AI nhận định" — 2-sentence summary + two-column Pros/Cons
      (Check / AlertTriangle icons) + "AI gợi ý" chips for extra
      personas, plus a "Làm mới" link that re-triggers the mutation.
  * 503 → amber banner. ADMIN users see a link to /admin/settings/ai.
  * Other errors → red banner with retry.
- listing-detail-client.tsx mounts <AiAdviceCards listingId=... /> in
  the sidebar between the social-share card and the stats block.
  Existing <AiEstimateButton> kept untouched next to it.

Constraints preserved
---------------------
- No new npm packages; no @anthropic-ai/sdk.
- Runtime imports for NestJS DI classes.
- API key read at request time only — nothing persists it outside
  SystemSetting.

Verification
------------
- API typecheck clean; 1975 / 1975 tests pass.
- Web typecheck clean in touched files; 624 / 624 tests pass.
- AiAdviceCards spec-mocked in listing-detail-client.spec so
  QueryClientProvider isn't required.

User can now set their Anthropic key via /admin/settings/ai and click
"Xem phân tích AI" on any listing detail to get valuation + advice.

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

apps/web/components/listings/__tests__/listing-detail-client.spec.tsx

@@ -43,15 +43,39 @@ vi.mock('@/components/valuation/ai-estimate-button', () => ({
   ),
 }));
 
+// Mock AiAdviceCards (pulls in @tanstack/react-query which needs a provider)
+vi.mock('@/components/listings/ai-advice-cards', () => ({
+  AiAdviceCards: ({ listingId }: { listingId: string }) => (
+    <button data-testid={`ai-advice-${listingId}`}>AI Advice</button>
+  ),
+}));
+
 // Mock InquiryModal
 vi.mock('@/components/listings/inquiry-modal', () => ({
   InquiryModal: () => null,
 }));
 
-// Mock analytics API (used for nearby POIs fetch)
+// Mock analytics API (used for nearby POIs fetch + AI advice)
 vi.mock('@/lib/analytics-api', () => ({
   analyticsApi: {
     getNearbyPOIs: vi.fn().mockResolvedValue({ pois: [], center: { lat: 0, lng: 0 } }),
+    getListingAiAdvice: vi.fn().mockResolvedValue({
+      valuation: {
+        estimateVND: 3_500_000_000,
+        lowVND: 3_000_000_000,
+        highVND: 4_000_000_000,
+        confidence: 'medium',
+        rationale: 'Giá hợp lý cho khu vực',
+      },
+      advice: {
+        summary: 'Tổng quan AI',
+        pros: ['Vị trí đẹp'],
+        cons: ['Giá cao hơn trung bình'],
+        suitableFor: ['Gia đình trẻ'],
+      },
+      model: 'claude-opus-4-5',
+      cacheHit: false,
+    }),
   },
 }));
 

apps/web/components/listings/ai-advice-cards.tsx

@@ -0,0 +1,257 @@
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { AlertTriangle, Check, RefreshCw, Sparkles } from 'lucide-react';
+import Link from 'next/link';
+import * as React from 'react';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { ApiError } from '@/lib/api-client';
+import { analyticsApi } from '@/lib/analytics-api';
+import type { AiConfidence, ListingAiAdvice } from '@/lib/analytics-api';
+import { useAuthStore } from '@/lib/auth-store';
+import { formatPrice } from '@/lib/currency';
+
+interface AiAdviceCardsProps {
+  listingId: string;
+  /** suitableFor labels already shown by the PersonaFitCard — used to de-dupe. */
+  existingPersonas?: string[];
+}
+
+const CONFIDENCE_STYLE: Record<AiConfidence, { label: string; variant: 'success' | 'warning' | 'destructive' }> = {
+  high: { label: 'Độ tin cậy cao', variant: 'success' },
+  medium: { label: 'Độ tin cậy trung bình', variant: 'warning' },
+  low: { label: 'Độ tin cậy thấp', variant: 'destructive' },
+};
+
+export function AiAdviceCards({ listingId, existingPersonas = [] }: AiAdviceCardsProps) {
+  const user = useAuthStore((s) => s.user);
+  const isAdmin = user?.role === 'ADMIN';
+
+  const mutation = useMutation<ListingAiAdvice, unknown, void>({
+    mutationFn: () => analyticsApi.getListingAiAdvice(listingId),
+  });
+
+  const { data, error, isPending, isSuccess } = mutation;
+
+  // Not loaded yet — show trigger button.
+  if (!isSuccess && !isPending && !error) {
+    return (
+      <Card className="border-primary/30 bg-primary/5">
+        <CardContent className="py-4">
+          <Button
+            type="button"
+            variant="outline"
+            className="w-full gap-2"
+            onClick={() => mutation.mutate()}
+          >
+            <Sparkles className="h-4 w-4" />
+            Xem phân tích AI
+          </Button>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  // Loading — skeleton.
+  if (isPending) {
+    return (
+      <Card className="border-primary/30 bg-primary/5">
+        <CardHeader className="pb-2">
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Sparkles className="h-4 w-4 animate-pulse text-primary" />
+            AI đang phân tích…
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <div className="h-6 w-3/4 animate-pulse rounded bg-muted" />
+          <div className="h-4 w-1/2 animate-pulse rounded bg-muted" />
+          <div className="h-3 w-full animate-pulse rounded bg-muted" />
+          <div className="h-3 w-5/6 animate-pulse rounded bg-muted" />
+        </CardContent>
+      </Card>
+    );
+  }
+
+  // Error state.
+  if (error) {
+    const apiErr = error instanceof ApiError ? error : null;
+    const status = apiErr?.status ?? 0;
+    const notConfigured = status === 503;
+
+    if (notConfigured) {
+      return (
+        <Card className="border-amber-200 bg-amber-50 dark:border-amber-900 dark:bg-amber-950/40">
+          <CardContent className="space-y-2 py-4">
+            <p className="flex items-start gap-2 text-sm">
+              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-amber-600" />
+              <span>AI chưa được cấu hình. Liên hệ quản trị viên.</span>
+            </p>
+            {isAdmin && (
+              <Link
+                href="/admin/settings/ai"
+                className="inline-flex items-center gap-1 text-xs font-medium text-primary underline"
+              >
+                Cấu hình Claude API →
+              </Link>
+            )}
+          </CardContent>
+        </Card>
+      );
+    }
+
+    return (
+      <Card className="border-destructive/40 bg-destructive/5">
+        <CardContent className="space-y-2 py-4">
+          <p className="flex items-start gap-2 text-sm text-destructive">
+            <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+            <span>
+              Không lấy được phân tích AI. {apiErr?.message ?? 'Vui lòng thử lại.'}
+            </span>
+          </p>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            className="gap-2"
+            onClick={() => mutation.mutate()}
+          >
+            <RefreshCw className="h-3.5 w-3.5" />
+            Thử lại
+          </Button>
+        </CardContent>
+      </Card>
+    );
+  }
+
+  // Success — render the two cards.
+  if (!data) return null;
+
+  const { valuation, advice } = data;
+  const confStyle = CONFIDENCE_STYLE[valuation.confidence] ?? CONFIDENCE_STYLE.medium;
+  const extraPersonas = advice.suitableFor.filter(
+    (p) => !existingPersonas.includes(p),
+  );
+
+  return (
+    <div className="space-y-6">
+      {/* Card 1 — AI định giá */}
+      <Card className="border-primary/30 bg-primary/5">
+        <CardHeader className="pb-2">
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Sparkles className="h-4 w-4 text-primary" />
+            AI định giá
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <div className="text-center">
+            <p className="text-2xl font-bold text-primary md:text-3xl">
+              {formatPrice(valuation.estimateVND)} VND
+            </p>
+            <p className="mt-1 text-xs text-muted-foreground">
+              Khoảng {formatPrice(valuation.lowVND)} – {formatPrice(valuation.highVND)} VND
+            </p>
+            <div className="mt-2 flex justify-center">
+              <Badge variant={confStyle.variant}>{confStyle.label}</Badge>
+            </div>
+          </div>
+          {valuation.rationale && (
+            <p
+              className="text-xs leading-relaxed text-muted-foreground"
+              style={{
+                display: '-webkit-box',
+                WebkitLineClamp: 3,
+                WebkitBoxOrient: 'vertical',
+                overflow: 'hidden',
+              }}
+            >
+              {valuation.rationale}
+            </p>
+          )}
+        </CardContent>
+      </Card>
+
+      {/* Card 2 — AI nhận định */}
+      <Card className="border-primary/30 bg-primary/5">
+        <CardHeader className="pb-2">
+          <CardTitle className="flex items-center gap-2 text-base">
+            <Sparkles className="h-4 w-4 text-primary" />
+            AI nhận định
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {advice.summary && (
+            <p className="text-sm leading-relaxed">{advice.summary}</p>
+          )}
+
+          <div className="grid gap-4 sm:grid-cols-2">
+            {advice.pros.length > 0 && (
+              <div>
+                <p className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                  Điểm mạnh
+                </p>
+                <ul className="space-y-1.5">
+                  {advice.pros.map((p, i) => (
+                    <li key={`pro-${i}`} className="flex items-start gap-1.5 text-sm">
+                      <Check className="mt-0.5 h-4 w-4 shrink-0 text-green-600" />
+                      <span>{p}</span>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            )}
+
+            {advice.cons.length > 0 && (
+              <div>
+                <p className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                  Cần cân nhắc
+                </p>
+                <ul className="space-y-1.5">
+                  {advice.cons.map((c, i) => (
+                    <li key={`con-${i}`} className="flex items-start gap-1.5 text-sm">
+                      <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-amber-600" />
+                      <span>{c}</span>
+                    </li>
+                  ))}
+                </ul>
+              </div>
+            )}
+          </div>
+
+          {extraPersonas.length > 0 && (
+            <div>
+              <p className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+                Phù hợp với
+              </p>
+              <div className="flex flex-wrap gap-2">
+                {extraPersonas.map((p) => (
+                  <div
+                    key={`ai-persona-${p}`}
+                    className="inline-flex items-center gap-1.5 rounded-full border border-primary/40 bg-primary/10 px-3 py-1 text-xs"
+                  >
+                    <span className="font-medium">{p}</span>
+                    <span className="rounded bg-primary/20 px-1 py-0.5 text-[9px] uppercase tracking-wide text-primary">
+                      AI gợi ý
+                    </span>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+
+          <div className="border-t pt-2 text-right">
+            <button
+              type="button"
+              className="inline-flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground"
+              onClick={() => mutation.mutate()}
+            >
+              <RefreshCw className="h-3 w-3" />
+              Làm mới
+            </button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

apps/web/components/listings/listing-detail-client.tsx

@@ -4,6 +4,7 @@ import dynamic from 'next/dynamic';
 import Link from 'next/link';
 import * as React from 'react';
 import { AddToCompareButton } from '@/components/comparison/add-to-compare-button';
+import { AiAdviceCards } from '@/components/listings/ai-advice-cards';
 import { ImageGallery } from '@/components/listings/image-gallery';
 import { InquiryModal } from '@/components/listings/inquiry-modal';
 import { PriceHistoryChart } from '@/components/listings/price-history-chart';
@@ -436,9 +437,15 @@ export function ListingDetailClient({ listing }: ListingDetailClientProps) {
             </CardContent>
           </Card>
 
-          {/* AI Estimate */}
+          {/* AI Estimate (legacy AVM — preserved) */}
           <AiEstimateButton listingId={listing.id} />
 
+          {/* AI advisor (Claude — analysis + valuation) */}
+          <AiAdviceCards
+            listingId={listing.id}
+            existingPersonas={property.suitableFor ?? []}
+          />
+
           {/* Stats */}
           <Card>
             <CardContent className="pt-6">