feat(projects): bring residential-project detail to parity with listings (4 phases)

Phase 1 — live POI + neighborhood score on project detail
- du-an-detail-client fetches `/analytics/pois/nearby` + `/analytics/neighborhoods/:district/score`
- Falls back to admin-entered `project.pois` / `neighborhoodScores` when endpoint returns nothing
- Adds total-score badge next to the radar chart (matches listings)

Phase 2 — project personas derivation (`lib/project-personas.ts`)
- Derives 8 personas from project-specific signals: property-type mix, amenity keywords,
  developer reputation, completion timing, status, live score + POIs
- Merges admin-authored `suitableFor` chips (badged "Chủ đầu tư chọn") with derived chips
- `composeWhyThisProject()` narrative used as fallback when admin hasn't authored one;
  badged "Tự động tổng hợp" so users know it's derived

Phase 3 — AI advisor for projects
- Extract shared Anthropic transport + JSON parsers to
  `analytics/application/queries/_shared/ai-json-client.ts` (dual auth: x-api-key +
  Bearer for proxy gateways)
- Refactor `GetListingAiAdviceHandler` to use the shared client
- New `GetProjectAiAdviceHandler` (CQRS) pulls project detail + optional POIs + score,
  builds project-flavored prompt, returns `{ advice: { summary, pros, cons, suitableFor } }`.
  No valuation block — project price is a range, not a single unit.
- `POST /analytics/projects/:id/ai-advice` endpoint (JWT-guarded)
- `ErrorCode.PROJECT_NOT_FOUND` added
- Frontend: `ProjectAiAdviceCard` mirrors listings card minus valuation, with loading /
  not-configured (503) / error states; dedupes AI-suggested personas against existing chips

Phase 4 — Mapbox LocationPicker in project create form
- New project page now renders `<LocationPicker>` with Vietnam-scoped geocoder; click /
  drag / search autofills lat+lng and (when empty) address/ward/district/city
- Edit page notes location immutability — backend `UpdateProjectCommand` does not yet
  accept lat/lng/address mutations (follow-up needed to enable editing coords)

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

apps/web/app/[locale]/(dashboard)/projects/[id]/edit/page.tsx

@@ -336,16 +336,26 @@ export default function EditProjectPage() {
           </div>
         </FormSection>
 
-        {/* Vị trí */}
+        {/* Vị trí (hiện tại chỉ hiển thị; backend chưa hỗ trợ sửa toạ độ sau khi tạo) */}
         <FormSection title="Vị trí">
-          <div className="space-y-1.5 sm:col-span-2 text-sm text-muted-foreground">
-            {project.address}
-            <br />
-            {project.district}, {project.city}
-            <br />
-            <span className="text-xs">
-              (Vị trí địa lý không thể chỉnh sửa sau khi tạo.)
-            </span>
+          <div className="sm:col-span-2 space-y-2 text-sm">
+            <div className="text-muted-foreground">
+              <span className="font-medium text-foreground">{project.address}</span>
+              <br />
+              {project.district}, {project.city}
+              {typeof project.latitude === 'number' && typeof project.longitude === 'number' && (
+                <>
+                  <br />
+                  <span className="text-xs">
+                    ({project.latitude.toFixed(6)}, {project.longitude.toFixed(6)})
+                  </span>
+                </>
+              )}
+            </div>
+            <p className="text-xs text-muted-foreground">
+              Vị trí địa lý hiện chưa thể chỉnh sửa sau khi tạo. Nếu cần cập nhật,
+              vui lòng xoá dự án và tạo lại.
+            </p>
           </div>
         </FormSection>
 

apps/web/app/[locale]/(dashboard)/projects/new/page.tsx

@@ -3,6 +3,7 @@
 import { zodResolver } from '@hookform/resolvers/zod';
 import { ArrowLeft } from 'lucide-react';
 import Link from 'next/link';
+import dynamic from 'next/dynamic';
 import { useRouter } from 'next/navigation';
 import * as React from 'react';
 import { useForm } from 'react-hook-form';
@@ -15,6 +16,18 @@ import { Select } from '@/components/ui/select';
 import { Textarea } from '@/components/ui/textarea';
 import { duAnApi, type CreateProjectPayload } from '@/lib/du-an-api';
 
+const LocationPicker = dynamic(
+  () => import('@/components/map/location-picker').then((m) => m.LocationPicker),
+  {
+    ssr: false,
+    loading: () => (
+      <div className="flex h-[320px] items-center justify-center rounded-lg border border-dashed bg-muted text-sm text-muted-foreground">
+        Đang tải bản đồ…
+      </div>
+    ),
+  },
+);
+
 const SLUG_REGEX = /^[a-z0-9-]+$/;
 
 const projectSchema = z.object({
@@ -126,6 +139,8 @@ export default function CreateProjectPage() {
   const {
     register,
     handleSubmit,
+    setValue,
+    watch,
     formState: { errors },
   } = useForm<ProjectFormData>({
     resolver: zodResolver(projectSchema),
@@ -135,6 +150,36 @@ export default function CreateProjectPage() {
     },
   });
 
+  const latStr = watch('latitude');
+  const lngStr = watch('longitude');
+  const latNum = Number.parseFloat(latStr ?? '');
+  const lngNum = Number.parseFloat(lngStr ?? '');
+
+  const handlePickLocation = React.useCallback(
+    (
+      coords: { lat: number; lng: number },
+      resolved?: { address?: string; ward?: string; district?: string; city?: string },
+    ) => {
+      setValue('latitude', coords.lat.toFixed(6), { shouldValidate: true });
+      setValue('longitude', coords.lng.toFixed(6), { shouldValidate: true });
+      // Only autofill address fields when currently empty — don't clobber what
+      // the admin typed intentionally.
+      if (resolved?.address && !watch('address')) {
+        setValue('address', resolved.address, { shouldValidate: true });
+      }
+      if (resolved?.ward && !watch('ward')) {
+        setValue('ward', resolved.ward, { shouldValidate: true });
+      }
+      if (resolved?.district && !watch('district')) {
+        setValue('district', resolved.district, { shouldValidate: true });
+      }
+      if (resolved?.city && !watch('city')) {
+        setValue('city', resolved.city, { shouldValidate: true });
+      }
+    },
+    [setValue, watch],
+  );
+
   const onSubmit = async (data: ProjectFormData) => {
     setIsSubmitting(true);
     setError(null);
@@ -309,6 +354,19 @@ export default function CreateProjectPage() {
 
         {/* Vị trí */}
         <FormSection title="Vị trí">
+          <div className="sm:col-span-2">
+            <Label>Chọn vị trí trên bản đồ</Label>
+            <p className="mb-2 text-xs text-muted-foreground">
+              Nhấp vào bản đồ hoặc kéo pin để xác định toạ độ. Ô địa chỉ / phường /
+              quận / thành phố bên dưới sẽ tự điền nếu đang trống.
+            </p>
+            <LocationPicker
+              lat={Number.isFinite(latNum) ? latNum : null}
+              lng={Number.isFinite(lngNum) ? lngNum : null}
+              onChange={handlePickLocation}
+              height="360px"
+            />
+          </div>
           <div className="space-y-1.5 sm:col-span-2">
             <Label htmlFor="address">
               Địa chỉ <span className="text-destructive">*</span>

apps/web/components/du-an/du-an-detail-client.tsx

@@ -10,20 +10,21 @@ import {
   Home,
   MapPin,
   Phone,
-  Sparkles,
   X,
 } from 'lucide-react';
 import dynamic from 'next/dynamic';
 import Image from 'next/image';
 import * as React from 'react';
+import { ProjectAiAdviceCard } from '@/components/du-an/project-ai-advice-card';
 import { ImageGallery } from '@/components/listings/image-gallery';
-import type { POICategory } from '@/components/neighborhood';
+import type { POICategory, POIItem } from '@/components/neighborhood';
 import { Badge } from '@/components/ui/badge';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
+import { analyticsApi, type NearbyPOI } from '@/lib/analytics-api';
 import { formatPrice } from '@/lib/currency';
 import {
   PROJECT_PROPERTY_TYPE_LABELS,
@@ -32,8 +33,25 @@ import {
   duAnApi,
   type ProjectDetail,
 } from '@/lib/du-an-api';
+import { listingsApi, type NeighborhoodScoreResult } from '@/lib/listings-api';
+import {
+  composeWhyThisProject,
+  deriveProjectPersonas,
+  type ProjectPersona,
+} from '@/lib/project-personas';
 import { cn } from '@/lib/utils';
 
+function mapScoreToCategories(result: NeighborhoodScoreResult) {
+  return [
+    { category: 'education', label: 'Giáo dục', score: result.educationScore },
+    { category: 'healthcare', label: 'Y tế', score: result.healthcareScore },
+    { category: 'transport', label: 'Giao thông', score: result.transportScore },
+    { category: 'shopping', label: 'Mua sắm', score: result.shoppingScore },
+    { category: 'environment', label: 'Môi trường', score: result.greeneryScore },
+    { category: 'safety', label: 'An ninh', score: result.safetyScore },
+  ];
+}
+
 const PriceTrendChart = dynamic(
   () => import('@/components/charts/price-trend-chart').then((m) => m.PriceTrendChart),
   { ssr: false },
@@ -72,6 +90,39 @@ export function DuAnDetailClient({ project }: DuAnDetailClientProps) {
     'idle' | 'loading' | 'success' | 'error'
   >('idle');
 
+  // Live enrichments — fetched from analytics endpoints. Both degrade
+  // gracefully: if either endpoint fails, we fall back to the
+  // admin-entered `project.pois` / `project.neighborhoodScores` payload.
+  const [liveScore, setLiveScore] = React.useState<NeighborhoodScoreResult | null>(null);
+  const [livePois, setLivePois] = React.useState<POIItem[] | null>(null);
+
+  React.useEffect(() => {
+    if (!project.district || !project.city) return;
+    listingsApi
+      .getNeighborhoodScore(project.district, project.city)
+      .then(setLiveScore)
+      .catch(() => {/* silent — LocationTab falls back to admin payload */});
+  }, [project.district, project.city]);
+
+  React.useEffect(() => {
+    const { latitude, longitude } = project;
+    if (latitude == null || longitude == null) return;
+    analyticsApi
+      .getNearbyPOIs(latitude, longitude)
+      .then((res) => {
+        const mapped: POIItem[] = res.pois.map((p: NearbyPOI) => ({
+          id: p.id,
+          name: p.name,
+          category: p.category,
+          lat: p.lat,
+          lng: p.lng,
+          distance: p.distance,
+        }));
+        setLivePois(mapped);
+      })
+      .catch(() => {/* silent — map still renders without POIs */});
+  }, [project.latitude, project.longitude]);
+
   const statusLabel = PROJECT_STATUS_LABELS[project.status];
   const statusColor = PROJECT_STATUS_COLORS[project.status];
 
@@ -155,11 +206,26 @@ export function DuAnDetailClient({ project }: DuAnDetailClientProps) {
         />
       </div>
 
-      {/* Persona fit — "Phù hợp với ai" (CĐT chọn) + AI placeholder */}
-      <ProjectPersonaFitCard project={project} />
+      {/* Persona fit — admin chips (CĐT chọn) merged with derived personas */}
+      <ProjectPersonaFitCard project={project} score={liveScore} pois={livePois ?? []} />
 
-      {/* "Vì sao nên chọn dự án này" narrative — admin authored */}
-      <ProjectWhyLocationCard project={project} />
+      {/* AI advisor card — on-demand Claude call for summary + pros/cons + personas */}
+      <div className="my-6">
+        <ProjectAiAdviceCard
+          projectId={project.id}
+          existingPersonas={[
+            ...(project.suitableFor ?? []),
+            ...deriveProjectPersonas(
+              project,
+              liveScore,
+              (livePois ?? []).map((p) => ({ category: p.category })),
+            ).map((d) => d.label),
+          ]}
+        />
+      </div>
+
+      {/* "Vì sao nên chọn dự án này" — admin narrative (preferred) or derived */}
+      <ProjectWhyLocationCard project={project} score={liveScore} pois={livePois ?? []} />
 
       <div className="grid gap-6 lg:grid-cols-3">
         {/* Main content */}
@@ -228,7 +294,9 @@ export function DuAnDetailClient({ project }: DuAnDetailClientProps) {
 
             <div className="mt-4">
               {activeTab === 'amenities' && <AmenitiesTab project={project} />}
-              {activeTab === 'location' && <LocationTab project={project} />}
+              {activeTab === 'location' && (
+                <LocationTab project={project} liveScore={liveScore} livePois={livePois} />
+              )}
               {activeTab === 'price' && <PriceTab project={project} />}
               {activeTab === 'listings' && <ListingsTab project={project} />}
               {activeTab === 'documents' && <DocumentsTab project={project} />}
@@ -410,18 +478,41 @@ const POI_TYPE_MAP: Record<string, POICategory> = {
   park: 'park',
 };
 
-function LocationTab({ project }: { project: ProjectDetail }) {
-  const mapPois = project.pois.map((poi) => ({
-    id: poi.id,
-    name: poi.name,
-    category: (POI_TYPE_MAP[poi.type] || 'shopping') as POICategory,
-    lat: poi.latitude,
-    lng: poi.longitude,
-    distance: poi.distance,
-  }));
-
+function LocationTab({
+  project,
+  liveScore,
+  livePois,
+}: {
+  project: ProjectDetail;
+  liveScore: NeighborhoodScoreResult | null;
+  livePois: POIItem[] | null;
+}) {
   const hasCoordinates = project.latitude != null && project.longitude != null;
 
+  // Prefer live POIs from the analytics endpoint; fall back to the admin-entered
+  // `project.pois` payload (useful before POIs are seeded for the district).
+  const mapPois: POIItem[] =
+    livePois && livePois.length > 0
+      ? livePois
+      : project.pois.map((poi) => ({
+          id: poi.id,
+          name: poi.name,
+          category: (POI_TYPE_MAP[poi.type] || 'shopping') as POICategory,
+          lat: poi.latitude,
+          lng: poi.longitude,
+          distance: poi.distance,
+        }));
+
+  // Prefer live neighborhood score from the analytics endpoint; fall back to
+  // whatever the detail payload embedded (category-level scores only).
+  const scoreCategories = liveScore
+    ? mapScoreToCategories(liveScore)
+    : project.neighborhoodScores.map((s) => ({
+        category: s.category,
+        label: s.label,
+        score: s.score,
+      }));
+
   return (
     <div className="space-y-6">
       <p className="text-sm">
@@ -429,45 +520,46 @@ function LocationTab({ project }: { project: ProjectDetail }) {
       </p>
 
       {/* Map */}
-      {hasCoordinates && (
-        <NeighborhoodPOIMap
-          center={{ lat: project.latitude!, lng: project.longitude! }}
-          pois={mapPois}
-          height="400px"
-        />
-      )}
-
-      {/* Neighborhood scores radar chart */}
-      {project.neighborhoodScores.length > 0 && (
-        <div>
-          <h4 className="mb-2 text-sm font-medium">Đánh giá khu vực</h4>
-          <NeighborhoodRadarChart
-            categories={project.neighborhoodScores.map((s) => ({
-              category: s.category,
-              label: s.label,
-              score: s.score,
-            }))}
-            height={300}
+      {hasCoordinates ? (
+        <>
+          <NeighborhoodPOIMap
+            center={{ lat: project.latitude!, lng: project.longitude! }}
+            pois={mapPois}
+            height="400px"
           />
+          <p className="text-sm text-muted-foreground">
+            {livePois
+              ? `Tìm thấy ${mapPois.length} điểm quan tâm trong bán kính 2 km`
+              : `Hiển thị ${mapPois.length} điểm đã được cập nhật thủ công`}
+          </p>
+        </>
+      ) : (
+        <div className="flex h-[300px] items-center justify-center rounded-lg bg-muted">
+          <p className="text-sm text-muted-foreground">Chưa có tọa độ cho dự án này</p>
         </div>
       )}
 
-      {/* POI list fallback (when no map) */}
-      {!hasCoordinates && project.pois.length > 0 && (
+      {/* Neighborhood score */}
+      {scoreCategories.length > 0 && (
         <div>
-          <h4 className="mb-2 text-sm font-medium">Tiện ích lân cận</h4>
-          <div className="space-y-2">
-            {project.pois.slice(0, 10).map((poi) => (
-              <div key={poi.id} className="flex items-center justify-between text-sm">
-                <span>{poi.name}</span>
-                <span className="text-muted-foreground">
-                  {poi.distance < 1000
-                    ? `${poi.distance}m`
-                    : `${(poi.distance / 1000).toFixed(1)}km`}
-                </span>
-              </div>
-            ))}
+          <div className="mb-3 flex items-center gap-2">
+            <h4 className="text-sm font-medium">Đánh giá khu vực</h4>
+            {liveScore && (
+              <Badge
+                variant={
+                  liveScore.totalScore > 7
+                    ? 'success'
+                    : liveScore.totalScore >= 5
+                      ? 'warning'
+                      : 'destructive'
+                }
+                className="px-2.5 py-0.5 text-sm font-bold"
+              >
+                {liveScore.totalScore.toFixed(1)}/10
+              </Badge>
+            )}
           </div>
+          <NeighborhoodRadarChart categories={scoreCategories} height={300} />
         </div>
       )}
     </div>
@@ -624,65 +716,121 @@ function ListingsTab({ project }: { project: ProjectDetail }) {
   );
 }
 
-function ProjectPersonaFitCard({ project }: { project: ProjectDetail }) {
-  const suitableFor = project.suitableFor ?? [];
+function ProjectPersonaFitCard({
+  project,
+  score,
+  pois,
+}: {
+  project: ProjectDetail;
+  score: NeighborhoodScoreResult | null;
+  pois: POIItem[];
+}) {
+  const adminLabels = project.suitableFor ?? [];
+  const derived: ProjectPersona[] = React.useMemo(
+    () =>
+      deriveProjectPersonas(
+        project,
+        score,
+        pois.map((p) => ({ category: p.category })),
+      ),
+    [project, score, pois],
+  );
 
-  // Always render the card so the "AI nhận định" CTA is visible even without
-  // admin-authored chips. If we eventually have nothing to show at all (no
-  // chips and we drop the placeholder), bail out early.
-  if (suitableFor.length === 0) {
-    // Still render with the AI placeholder so users see the intent.
-  }
+  // Deduplicate: if an admin chip matches a derived persona label, keep the
+  // admin chip (it wins; CĐT knows their target audience best).
+  const adminSet = new Set(adminLabels.map((l) => l.toLowerCase()));
+  const derivedFiltered = derived.filter((p) => !adminSet.has(p.label.toLowerCase()));
+
+  if (adminLabels.length === 0 && derivedFiltered.length === 0) return null;
 
   return (
     <Card className="my-6 border-primary/30 bg-primary/5">
       <CardHeader className="pb-3">
         <CardTitle className="text-lg">Phù hợp với ai?</CardTitle>
       </CardHeader>
-      <CardContent className="space-y-4">
-        {suitableFor.length > 0 ? (
-          <div className="flex flex-wrap gap-2">
-            {suitableFor.map((label) => (
+      <CardContent>
+        <div className="flex flex-wrap gap-2">
+          {/* Admin-authored chips first, marked with badge. */}
+          {adminLabels.map((label) => (
+            <div
+              key={`admin-${label}`}
+              className="inline-flex items-center gap-1.5 rounded-full border border-primary/50 bg-primary/10 px-3 py-1.5 text-sm shadow-sm"
+            >
+              <span className="font-medium">{label}</span>
+              <span className="rounded bg-primary/20 px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-primary">
+                Chủ đầu tư chọn
+              </span>
+            </div>
+          ))}
+          {/* Derived personas — include short reason on hover via title. */}
+          {derivedFiltered.map((p) => {
+            const Icon = p.icon;
+            return (
               <div
-                key={`admin-${label}`}
-                className="inline-flex items-center gap-1.5 rounded-full border border-primary/50 bg-primary/10 px-3 py-1.5 text-sm shadow-sm"
+                key={`derived-${p.key}`}
+                title={p.reason}
+                className="inline-flex items-center gap-1.5 rounded-full border bg-card px-3 py-1.5 text-sm shadow-sm"
               >
-                <span className="font-medium">{label}</span>
-                <span className="rounded bg-primary/20 px-1.5 py-0.5 text-[10px] uppercase tracking-wide text-primary">
-                  Chủ đầu tư chọn
-                </span>
+                <Icon className="h-3.5 w-3.5 text-primary" aria-hidden="true" />
+                <span className="font-medium">{p.label}</span>
               </div>
-            ))}
-          </div>
-        ) : (
-          <p className="text-sm text-muted-foreground">
-            Chủ đầu tư chưa chỉ định nhóm khách phù hợp.
-          </p>
-        )}
-
-        {/* TODO: replace with a real project-AI advisor endpoint (see the
-            listings flow: apps/api/src/modules/analytics/application/queries/
-            get-listing-ai-advice/). For now this is a disabled placeholder to
-            signal intent without shipping a half-built integration. */}
-        <div className="pt-1">
-          <Button type="button" variant="outline" disabled className="gap-2">
-            <Sparkles className="h-4 w-4" />
-            AI nhận định dự án (sắp ra mắt)
-          </Button>
+            );
+          })}
         </div>
+
+        {/* Per-persona reasons — expanded list so users see the "vì sao". */}
+        {derivedFiltered.length > 0 && (
+          <ul className="mt-4 space-y-1.5 text-sm text-muted-foreground">
+            {derivedFiltered.map((p) => (
+              <li key={`reason-${p.key}`} className="flex items-start gap-2">
+                <span className="mt-2 h-1 w-1 shrink-0 rounded-full bg-primary" aria-hidden="true" />
+                <span>
+                  <span className="font-medium text-foreground">{p.label}:</span> {p.reason}
+                </span>
+              </li>
+            ))}
+          </ul>
+        )}
       </CardContent>
     </Card>
   );
 }
 
-function ProjectWhyLocationCard({ project }: { project: ProjectDetail }) {
-  const narrative = project.whyThisLocation?.trim();
+function ProjectWhyLocationCard({
+  project,
+  score,
+  pois,
+}: {
+  project: ProjectDetail;
+  score: NeighborhoodScoreResult | null;
+  pois: POIItem[];
+}) {
+  const adminNarrative = project.whyThisLocation?.trim();
+  const derivedNarrative = React.useMemo(
+    () =>
+      composeWhyThisProject(
+        project,
+        score,
+        pois.map((p) => ({ category: p.category })),
+      ),
+    [project, score, pois],
+  );
+
+  // Prefer admin-authored narrative; fall back to derived. Bail out if neither.
+  const narrative = adminNarrative || derivedNarrative;
   if (!narrative) return null;
 
   return (
     <Card className="my-6">
       <CardHeader className="pb-3">
-        <CardTitle className="text-lg">Vì sao nên chọn dự án này?</CardTitle>
+        <CardTitle className="flex items-center gap-2 text-lg">
+          Vì sao nên chọn dự án này?
+          {!adminNarrative && (
+            <Badge variant="outline" className="text-[10px] uppercase tracking-wide">
+              Tự động tổng hợp
+            </Badge>
+          )}
+        </CardTitle>
       </CardHeader>
       <CardContent>
         <p className="whitespace-pre-wrap text-sm leading-relaxed">{narrative}</p>

apps/web/components/du-an/project-ai-advice-card.tsx

@@ -0,0 +1,211 @@
+'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 { Button } from '@/components/ui/button';
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { analyticsApi, type ProjectAiAdvice } from '@/lib/analytics-api';
+import { ApiError } from '@/lib/api-client';
+import { useAuthStore } from '@/lib/auth-store';
+
+interface ProjectAiAdviceCardProps {
+  projectId: string;
+  /**
+   * Persona labels already rendered by ProjectPersonaFitCard. We de-dupe
+   * before showing AI-suggested ones so users don't see the same chip twice.
+   */
+  existingPersonas?: string[];
+}
+
+export function ProjectAiAdviceCard({
+  projectId,
+  existingPersonas = [],
+}: ProjectAiAdviceCardProps) {
+  const user = useAuthStore((s) => s.user);
+  const isAdmin = user?.role === 'ADMIN';
+
+  const mutation = useMutation<ProjectAiAdvice, unknown, void>({
+    mutationFn: () => analyticsApi.getProjectAiAdvice(projectId),
+  });
+
+  const { data, error, isPending, isSuccess } = mutation;
+
+  // Initial state — 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 về dự án
+          </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 dự án…
+          </CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-3">
+          <div className="h-4 w-3/4 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" />
+          <div className="h-3 w-2/3 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>
+    );
+  }
+
+  if (!data) return null;
+
+  const { advice } = data;
+  const extraPersonas = advice.suitableFor.filter(
+    (p) => !existingPersonas.includes(p),
+  );
+
+  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 text-primary" />
+          AI nhận định dự án
+        </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>
+  );
+}

apps/web/lib/analytics-api.ts

@@ -121,6 +121,19 @@ export interface ListingAiAdvice {
   };
 }
 
+/** Project AI advice — same advice block as listings but no valuation. */
+export interface ProjectAiAdvice {
+  advice: ListingAiAdviceBody;
+  model: string;
+  cacheHit: boolean;
+  cacheUsage?: {
+    input: number;
+    cacheCreation: number;
+    cacheRead: number;
+    output: number;
+  };
+}
+
 export const analyticsApi = {
   getMarketReport: (city: string, period: string, propertyType?: string) => {
     const params = new URLSearchParams({ city, period });
@@ -150,4 +163,7 @@ export const analyticsApi = {
 
   getListingAiAdvice: (listingId: string) =>
     apiClient.post<ListingAiAdvice>(`/analytics/listings/${listingId}/ai-advice`),
+
+  getProjectAiAdvice: (projectId: string) =>
+    apiClient.post<ProjectAiAdvice>(`/analytics/projects/${projectId}/ai-advice`),
 };

apps/web/lib/project-personas.ts

@@ -0,0 +1,365 @@
+/**
+ * Derive "Phù hợp với ai" personas and compose a "Vì sao nên chọn dự án này"
+ * narrative for a Residential Project (dự án của chủ đầu tư).
+ *
+ * Mirrors `lib/listing-personas.ts` but keys off project-specific signals —
+ * developer reputation, amenity mix, status, completion timing, property-type
+ * composition, price tier — instead of per-unit fields (bedrooms/area).
+ *
+ * Purely client-side; no new backend fields required. Admin-authored
+ * `project.suitableFor` / `project.whyThisLocation` are merged on top.
+ */
+
+import {
+  Baby,
+  HeartPulse,
+  Home,
+  Laptop,
+  Shield,
+  TrainFront,
+  Trees,
+  TrendingUp,
+  type LucideIcon,
+} from 'lucide-react';
+import type { NearbyPOICategory } from './analytics-api';
+import type { ProjectDetail } from './du-an-api';
+import type { NeighborhoodScoreResult } from './listings-api';
+
+export type ProjectPersonaKey =
+  | 'family_with_kids'
+  | 'young_family'
+  | 'commuter'
+  | 'single_young'
+  | 'nature_lover'
+  | 'long_term_investor'
+  | 'safety_first'
+  | 'senior';
+
+export interface ProjectPersona {
+  key: ProjectPersonaKey;
+  label: string;
+  icon: LucideIcon;
+  reason: string;
+}
+
+const PERSONA_LABELS: Record<ProjectPersonaKey, { label: string; icon: LucideIcon }> = {
+  family_with_kids: { label: 'Gia đình có con nhỏ', icon: Baby },
+  young_family: { label: 'Gia đình trẻ', icon: Home },
+  commuter: { label: 'Người đi làm xa', icon: TrainFront },
+  single_young: { label: 'Người trẻ / độc thân', icon: Laptop },
+  nature_lover: { label: 'Yêu thiên nhiên', icon: Trees },
+  long_term_investor: { label: 'Nhà đầu tư dài hạn', icon: TrendingUp },
+  safety_first: { label: 'Ưu tiên an ninh', icon: Shield },
+  senior: { label: 'Người lớn tuổi', icon: HeartPulse },
+};
+
+type POICountByCategory = Partial<Record<NearbyPOICategory, number>>;
+
+function countPOIs(pois: Array<{ category: NearbyPOICategory }>): POICountByCategory {
+  const counts: POICountByCategory = {};
+  for (const p of pois) {
+    counts[p.category] = (counts[p.category] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/** Case-insensitive keyword hit across amenity.name + amenity.category. */
+function amenityMatches(project: ProjectDetail, keywords: string[]): number {
+  const hay = project.amenities
+    .flatMap((a) => [a.name, a.category])
+    .join(' | ')
+    .toLowerCase();
+  let hits = 0;
+  for (const kw of keywords) {
+    if (hay.includes(kw.toLowerCase())) hits += 1;
+  }
+  return hits;
+}
+
+function hasPropertyType(
+  project: ProjectDetail,
+  types: Array<ProjectDetail['propertyTypes'][number]>,
+): boolean {
+  return project.propertyTypes.some((t) => types.includes(t));
+}
+
+/** Months until completionDate, or null if missing / already passed. */
+function monthsUntilCompletion(project: ProjectDetail): number | null {
+  if (!project.completionDate) return null;
+  const target = new Date(project.completionDate).getTime();
+  const now = Date.now();
+  if (Number.isNaN(target) || target <= now) return null;
+  return Math.round((target - now) / (1000 * 60 * 60 * 24 * 30));
+}
+
+export function deriveProjectPersonas(
+  project: ProjectDetail,
+  score: NeighborhoodScoreResult | null,
+  pois: Array<{ category: NearbyPOICategory }>,
+): ProjectPersona[] {
+  const poiCount = countPOIs(pois);
+  const out: ProjectPersona[] = [];
+
+  // ─── Gia đình có con nhỏ ──────────────────────────────────
+  // Điểm giáo dục tốt + dự án có loại hình phù hợp cho gia đình (VILLA /
+  // TOWNHOUSE / căn hộ) hoặc amenities có khu vui chơi / mẫu giáo.
+  const kidAmenities = amenityMatches(project, [
+    'trẻ em',
+    'mẫu giáo',
+    'trường',
+    'kids',
+    'playground',
+    'khu vui chơi',
+  ]);
+  if (
+    (score && score.educationScore >= 7) ||
+    kidAmenities > 0 ||
+    hasPropertyType(project, ['VILLA', 'TOWNHOUSE'])
+  ) {
+    const schools = poiCount.school ?? 0;
+    const reasonBits: string[] = [];
+    if (score && score.educationScore >= 7)
+      reasonBits.push(`điểm giáo dục ${score.educationScore.toFixed(1)}/10`);
+    if (schools > 0) reasonBits.push(`${schools} trường học gần`);
+    if (kidAmenities > 0) reasonBits.push(`có ${kidAmenities} tiện ích cho trẻ em`);
+    if (hasPropertyType(project, ['VILLA', 'TOWNHOUSE']))
+      reasonBits.push('có biệt thự / nhà phố');
+    out.push({
+      ...PERSONA_LABELS.family_with_kids,
+      key: 'family_with_kids',
+      reason: reasonBits.length > 0
+        ? `${reasonBits.slice(0, 2).join(', ')}.`
+        : 'Phù hợp cho gia đình có con nhỏ.',
+    });
+  }
+
+  // ─── Gia đình trẻ ──────────────────────────────────────────
+  // APARTMENT + y tế tốt (2BR không hard-code vì project là tổ hợp).
+  if (
+    hasPropertyType(project, ['APARTMENT']) &&
+    score &&
+    score.healthcareScore >= 7
+  ) {
+    const hospitals = poiCount.hospital ?? 0;
+    out.push({
+      ...PERSONA_LABELS.young_family,
+      key: 'young_family',
+      reason: hospitals > 0
+        ? `Có ${hospitals} bệnh viện/phòng khám gần, y tế ${score.healthcareScore.toFixed(1)}/10.`
+        : `Y tế khu vực đạt ${score.healthcareScore.toFixed(1)}/10.`,
+    });
+  }
+
+  // ─── Người đi làm xa ───────────────────────────────────────
+  // Giao thông tốt hoặc có nhiều điểm metro/bus gần.
+  const transitCount = poiCount.transit ?? 0;
+  if ((score && score.transportScore >= 7) || transitCount >= 2) {
+    out.push({
+      ...PERSONA_LABELS.commuter,
+      key: 'commuter',
+      reason: transitCount >= 2
+        ? `${transitCount} điểm metro/bus trong 2km, giao thông ${score?.transportScore.toFixed(1) ?? '?'}/10.`
+        : `Giao thông ${score?.transportScore.toFixed(1) ?? '?'}/10.`,
+    });
+  }
+
+  // ─── Người trẻ / độc thân ─────────────────────────────────
+  // APARTMENT + shopping/restaurants tốt.
+  const restaurantCount = poiCount.restaurant ?? 0;
+  const shoppingCount = poiCount.shopping ?? 0;
+  if (
+    hasPropertyType(project, ['APARTMENT']) &&
+    score &&
+    (score.shoppingScore >= 7 || restaurantCount >= 2)
+  ) {
+    const detail: string[] = [];
+    if (restaurantCount >= 2) detail.push(`${restaurantCount} nhà hàng/quán cafe`);
+    if (shoppingCount >= 1) detail.push(`${shoppingCount} TTTM/siêu thị`);
+    detail.push(`mua sắm ${score.shoppingScore.toFixed(1)}/10`);
+    out.push({
+      ...PERSONA_LABELS.single_young,
+      key: 'single_young',
+      reason: `Gần ${detail.slice(0, 2).join(', ')}.`,
+    });
+  }
+
+  // ─── Yêu thiên nhiên ──────────────────────────────────────
+  // Môi trường tốt HOẶC có công viên gần HOẶC amenities có hồ bơi/công viên/cây xanh.
+  const greenAmenities = amenityMatches(project, [
+    'hồ bơi',
+    'công viên',
+    'cây xanh',
+    'hồ cảnh quan',
+    'pool',
+    'garden',
+  ]);
+  const parkCount = poiCount.park ?? 0;
+  if ((score && score.greeneryScore >= 7) || parkCount >= 1 || greenAmenities >= 2) {
+    const bits: string[] = [];
+    if (score && score.greeneryScore >= 7)
+      bits.push(`môi trường ${score.greeneryScore.toFixed(1)}/10`);
+    if (parkCount > 0) bits.push(`${parkCount} công viên gần`);
+    if (greenAmenities > 0) bits.push(`${greenAmenities} tiện ích xanh nội khu`);
+    out.push({
+      ...PERSONA_LABELS.nature_lover,
+      key: 'nature_lover',
+      reason: bits.slice(0, 2).join(', ') + '.',
+    });
+  }
+
+  // ─── Ưu tiên an ninh ──────────────────────────────────────
+  // Safety score cao hoặc amenities có security/camera/bảo vệ 24/24.
+  const safetyAmenities = amenityMatches(project, [
+    'bảo vệ',
+    'an ninh',
+    'camera',
+    'security',
+    '24/7',
+    '24/24',
+  ]);
+  if ((score && score.safetyScore >= 8) || safetyAmenities >= 2) {
+    const parts: string[] = [];
+    if (score && score.safetyScore >= 8) parts.push(`an ninh ${score.safetyScore.toFixed(1)}/10`);
+    if (safetyAmenities > 0) parts.push(`${safetyAmenities} lớp bảo vệ nội khu`);
+    out.push({
+      ...PERSONA_LABELS.safety_first,
+      key: 'safety_first',
+      reason: parts.join(', ') + '.',
+    });
+  }
+
+  // ─── Người lớn tuổi ───────────────────────────────────────
+  // Y tế + môi trường đều cao, ưu tiên dự án đã hoặc sắp bàn giao.
+  const hospitals = poiCount.hospital ?? 0;
+  const handoverSoon =
+    project.status === 'HANDOVER' ||
+    project.status === 'COMPLETED' ||
+    (monthsUntilCompletion(project) ?? 99) <= 6;
+  if (
+    score &&
+    score.healthcareScore >= 8 &&
+    score.greeneryScore >= 6 &&
+    handoverSoon
+  ) {
+    out.push({
+      ...PERSONA_LABELS.senior,
+      key: 'senior',
+      reason: hospitals > 0
+        ? `${hospitals} bệnh viện gần, y tế ${score.healthcareScore.toFixed(1)}/10, môi trường ${score.greeneryScore.toFixed(1)}/10.`
+        : `Y tế ${score.healthcareScore.toFixed(1)}/10, môi trường ${score.greeneryScore.toFixed(1)}/10.`,
+    });
+  }
+
+  // ─── Nhà đầu tư dài hạn ───────────────────────────────────
+  // Dự án đang xây / quy hoạch + CĐT có uy tín (>=5 dự án) + khu vực tốt
+  // + giao thông >= 7 (tiềm năng cho thuê / tăng giá).
+  const developerProven = project.developer.totalProjects >= 5;
+  const earlyStage =
+    project.status === 'PLANNING' || project.status === 'UNDER_CONSTRUCTION';
+  if (
+    earlyStage &&
+    developerProven &&
+    score &&
+    score.totalScore >= 7 &&
+    score.transportScore >= 7
+  ) {
+    const months = monthsUntilCompletion(project);
+    const timingBit = months != null ? `bàn giao sau ~${months} tháng` : 'bàn giao tương lai';
+    out.push({
+      ...PERSONA_LABELS.long_term_investor,
+      key: 'long_term_investor',
+      reason: `CĐT ${project.developer.totalProjects} dự án, khu vực ${score.totalScore.toFixed(1)}/10, ${timingBit}.`,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Compose a short narrative highlighting the strongest 2-3 reasons to choose
+ * this project. Returns null when there isn't enough signal. Blends live
+ * neighborhood score with project-specific advantages (developer, amenity mix,
+ * status) so the narrative is distinct from the listings version.
+ */
+export function composeWhyThisProject(
+  project: ProjectDetail,
+  score: NeighborhoodScoreResult | null,
+  pois: Array<{ category: NearbyPOICategory }>,
+): string | null {
+  const parts: string[] = [];
+  const poiCount = countPOIs(pois);
+
+  // Location highlights from the score radar.
+  if (score) {
+    const scoreEntries: Array<{ label: string; score: number; detail: string }> = [
+      {
+        label: 'giáo dục',
+        score: score.educationScore,
+        detail: poiCount.school
+          ? `${poiCount.school} trường học gần`
+          : 'hệ thống trường đa dạng',
+      },
+      {
+        label: 'y tế',
+        score: score.healthcareScore,
+        detail: poiCount.hospital
+          ? `${poiCount.hospital} bệnh viện trong 2km`
+          : 'tiện ích y tế đầy đủ',
+      },
+      {
+        label: 'giao thông',
+        score: score.transportScore,
+        detail: poiCount.transit
+          ? `${poiCount.transit} điểm metro/bus gần`
+          : 'dễ kết nối các khu vực khác',
+      },
+      {
+        label: 'mua sắm',
+        score: score.shoppingScore,
+        detail: poiCount.shopping
+          ? `${poiCount.shopping} siêu thị/TTTM gần`
+          : 'nhiều lựa chọn mua sắm',
+      },
+      {
+        label: 'môi trường',
+        score: score.greeneryScore,
+        detail: poiCount.park ? `${poiCount.park} công viên gần` : 'không gian xanh tốt',
+      },
+      { label: 'an ninh', score: score.safetyScore, detail: 'khu dân cư yên tĩnh' },
+    ];
+    const highlights = scoreEntries
+      .filter((e) => e.score >= 7)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 2);
+    for (const h of highlights) {
+      parts.push(
+        `${h.label.charAt(0).toUpperCase()}${h.label.slice(1)} đạt ${h.score.toFixed(1)}/10 (${h.detail})`,
+      );
+    }
+  }
+
+  // Project-level advantage: developer reputation.
+  if (project.developer.totalProjects >= 5) {
+    parts.push(
+      `CĐT ${project.developer.name} đã triển khai ${project.developer.totalProjects} dự án`,
+    );
+  }
+
+  // Amenity density highlight.
+  if (project.amenities.length >= 10) {
+    parts.push(`${project.amenities.length} tiện ích nội khu đa dạng`);
+  }
+
+  // Timing advantage.
+  const months = monthsUntilCompletion(project);
+  if (project.status === 'COMPLETED') {
+    parts.push('dự án đã hoàn thành, vào ở ngay');
+  } else if (project.status === 'HANDOVER') {
+    parts.push('đang bàn giao, sẵn sàng nhận nhà');
+  } else if (months != null && months <= 12) {
+    parts.push(`dự kiến bàn giao sau ~${months} tháng`);
+  }
+
+  if (parts.length === 0) return null;
+  return parts.slice(0, 4).join('. ') + '.';
+}