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/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>