feat(avm): end-to-end AVM v2 schema + POST /analytics/valuation endpoint

Closes the last gap from the tec-2725 branch: the valuation form's v2
extended-features section and POST endpoint can now submit real
predictions through to the Python ensemble model.

Backend
- New DTO apps/api/src/modules/analytics/presentation/dto/predict-valuation.dto.ts
  with all v1 fields + 8 v2 fields (useV2 toggle, distanceToHospital/Park/
  Mall in km, floodZoneRisk enum NONE|LOW|MEDIUM|HIGH, hasElevator/
  Parking/Pool booleans).
- New CQRS handler apps/api/src/modules/analytics/application/queries/
  predict-valuation/ that routes to AVM_SERVICE.estimateValue() with the
  full request body.
- Extend AVMParams (domain) with the same v2 fields + inline v1 fields
  (district, city, bedrooms, bathrooms, floors, frontage, roadWidth,
  hasLegalPaper, projectId, imageUrl, description, deepAnalysis).
- HttpAVMService.estimateViaAi now branches on `useV2`: v2 calls the new
  aiClient.predictV2() → POST /avm/v2/predict on the Python service,
  mapping floodZoneRisk enum → 0..1 float and computing
  building_age_years from yearBuilt. v1 path gets all the inline
  descriptors wired through so non-propertyId calls no longer lose
  context.
- AiServiceClient gets AiPredictV2Request / AiPredictV2Response types
  mirroring libs/ai-services/app/models/avm_v2.py::AVMv2PredictRequest
  (which already accepts all 7 numeric/boolean v2 fields — no Python
  change needed).
- Register PredictValuationHandler in AnalyticsModule.
- New route POST /analytics/valuation on AnalyticsController:
  JwtAuthGuard + QuotaGuard + EndpointRateLimitGuard (10/min),
  @RequireQuota('analytics_queries'), full Swagger doc. Total endpoint
  count 179 → 180.

Frontend
- Extend ValuationRequest with useV2, 3 distance-km fields,
  floodZoneRisk, hasElevator/Parking/Pool + export FloodZoneRisk type
  and FLOOD_RISK_OPTIONS.
- valuationApi.predict() body mapping now includes v2 fields and renames
  'areaM2' → 'area' to match the backend DTO contract.
- valuationFormSchema gains matching optional Zod fields + exports
  FLOOD_RISK_OPTIONS for the form.
- valuation-form.tsx gets:
  * Image upload hardening: MIME+size validation (JPG/PNG ≤5MB) before
    preview, role="progressbar" + aria-labels on the progress bar,
    role="alert" + data-testid="image-upload-error" on errors. Matches
    the upload-progress part of the task/tec-2725 commit 4ee0129 that
    was previously parked as blocked.
  * New Sparkles-branded "Mô hình v2 (Ensemble)" toggle alongside the
    existing Bot-branded "Phân tích chuyên sâu" toggle.
  * Collapsible "Đặc trưng mở rộng (AVM v2)" section with distance
    inputs, flood-risk select, and three amenity checkboxes.
  * handleFormSubmit passes all v2 fields through to onSubmit.

Python service unchanged — AVMv2PredictRequest already has every field
we send (distance_to_hospital_km, flood_zone_risk as float,
has_elevator/parking/pool, etc.).

Typecheck clean for the valuation surface. Pre-existing errors in
metadata.spec.ts and transfer-wizard-client.tsx are unrelated and left
for a follow-up.

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

apps/api/src/modules/analytics/infrastructure/services/ai-service.client.ts

@@ -23,6 +23,76 @@ export interface AiPredictResponse {
   price_range_high: number;
 }
 
+/**
+ * AVM v2 request — extended feature set for residential ensemble.
+ * Matches `AVMv2PredictRequest` in libs/ai-services/app/models/avm_v2.py.
+ */
+export interface AiPredictV2Request {
+  district: string;
+  city: string;
+  property_type: string;
+  area_m2: number;
+  distance_to_cbd_km?: number;
+  distance_to_metro_km?: number;
+  distance_to_school_km?: number;
+  distance_to_hospital_km?: number;
+  distance_to_park_km?: number;
+  distance_to_mall_km?: number;
+  flood_zone_risk?: number;
+  neighborhood_score?: number;
+  rooms?: number;
+  floor_level?: number;
+  total_floors?: number;
+  direction?: string;
+  floor_ratio?: number;
+  building_age_years?: number;
+  has_elevator?: boolean;
+  has_parking?: boolean;
+  has_pool?: boolean;
+  has_legal_paper?: boolean;
+  developer_reputation?: number;
+  avg_price_district_3m_vnd_m2?: number;
+  listing_density?: number;
+  absorption_rate?: number;
+  dom_avg?: number;
+  price_momentum_30d?: number;
+  yoy_change?: number;
+  renovation_score?: number;
+  view_quality?: number;
+  interior_quality?: number;
+  noise_level?: number;
+  natural_light?: number;
+  month?: number;
+  quarter?: number;
+  is_year_end?: boolean;
+}
+
+export interface AiPredictV2FeatureImportance {
+  feature: string;
+  importance: number;
+}
+
+export interface AiPredictV2Comparable {
+  district: string;
+  property_type: string;
+  area_m2: number;
+  price_vnd: number;
+  price_per_m2_vnd: number;
+  similarity_score: number;
+}
+
+export interface AiPredictV2Response {
+  estimated_price_vnd: number;
+  confidence: number;
+  price_per_m2_vnd: number;
+  price_range_low_vnd: number;
+  price_range_high_vnd: number;
+  drivers?: AiPredictV2FeatureImportance[];
+  comparables?: AiPredictV2Comparable[];
+  model_version?: string;
+  ensemble_method?: string;
+}
+
 export interface AiIndustrialPredictRequest {
   province: string;
   region: string;
@@ -124,6 +194,7 @@ export const AI_SERVICE_CLIENT = Symbol('AI_SERVICE_CLIENT');
 
 export interface IAiServiceClient {
   predict(req: AiPredictRequest): Promise<AiPredictResponse>;
+  predictV2(req: AiPredictV2Request): Promise<AiPredictV2Response>;
   predictIndustrial(req: AiIndustrialPredictRequest): Promise<AiIndustrialPredictResponse>;
   moderate(req: AiModerationRequest): Promise<AiModerationResponse>;
   scoreNeighborhood(req: AiNeighborhoodScoreRequest): Promise<AiNeighborhoodScoreResponse>;
@@ -146,6 +217,10 @@ export class AiServiceClient implements IAiServiceClient {
     return this.post<AiPredictResponse>('/avm/predict', req);
   }
 
+  async predictV2(req: AiPredictV2Request): Promise<AiPredictV2Response> {
+    return this.post<AiPredictV2Response>('/avm/v2/predict', req);
+  }
+
   async predictIndustrial(req: AiIndustrialPredictRequest): Promise<AiIndustrialPredictResponse> {
     return this.post<AiIndustrialPredictResponse>('/avm/industrial/predict', req);
   }

apps/api/src/modules/analytics/infrastructure/services/http-avm.service.ts

@@ -12,7 +12,16 @@ import {
   AI_SERVICE_CLIENT,
   type IAiServiceClient,
   type AiPredictRequest,
+  type AiPredictV2Request,
 } from './ai-service.client';
+
+/** Map string risk buckets to the 0..1 float the Python service expects. */
+const FLOOD_RISK_TO_SCORE: Record<string, number> = {
+  NONE: 0,
+  LOW: 0.33,
+  MEDIUM: 0.66,
+  HIGH: 1,
+};
 import { PrismaAVMService } from './prisma-avm.service';
 
 /** Max concurrency for batch AI calls to avoid overloading the Python service. */
@@ -83,18 +92,22 @@ export class HttpAVMService implements IAVMService {
       ? await this.getPropertyDetails(params.propertyId)
       : null;
 
+    if (params.useV2) {
+      return this.estimateViaAiV2(params, propertyData);
+    }
+
     const request: AiPredictRequest = {
       area: params.areaM2 ?? propertyData?.areaM2 ?? 0,
-      district: propertyData?.district ?? '',
-      city: propertyData?.city ?? '',
+      district: params.district ?? propertyData?.district ?? '',
+      city: params.city ?? propertyData?.city ?? '',
       property_type: (params.propertyType ?? propertyData?.propertyType ?? 'house').toLowerCase(),
-      bedrooms: propertyData?.bedrooms ?? 0,
-      bathrooms: propertyData?.bathrooms ?? 0,
-      floors: propertyData?.floors ?? 0,
-      frontage: 0,
-      road_width: 0,
+      bedrooms: params.bedrooms ?? propertyData?.bedrooms ?? 0,
+      bathrooms: params.bathrooms ?? propertyData?.bathrooms ?? 0,
+      floors: params.floors ?? propertyData?.floors ?? 0,
+      frontage: params.frontage ?? 0,
+      road_width: params.roadWidth ?? 0,
       year_built: params.yearBuilt ?? propertyData?.yearBuilt,
-      has_legal_paper: propertyData?.hasLegalPaper ?? true,
+      has_legal_paper: params.hasLegalPaper ?? propertyData?.hasLegalPaper ?? true,
     };
 
     const aiResult = await this.aiClient.predict(request);
@@ -118,6 +131,55 @@ export class HttpAVMService implements IAVMService {
     };
   }
 
+  private async estimateViaAiV2(
+    params: AVMParams,
+    propertyData: Awaited<ReturnType<HttpAVMService['getPropertyDetails']>>,
+  ): Promise<ValuationResult> {
+    const yearBuilt = params.yearBuilt ?? propertyData?.yearBuilt ?? null;
+    const now = new Date();
+
+    const v2Request: AiPredictV2Request = {
+      district: params.district ?? propertyData?.district ?? '',
+      city: params.city ?? propertyData?.city ?? '',
+      property_type: (params.propertyType ?? propertyData?.propertyType ?? 'house').toLowerCase(),
+      area_m2: params.areaM2 ?? propertyData?.areaM2 ?? 0,
+      distance_to_hospital_km: params.distanceToHospitalKm,
+      distance_to_park_km: params.distanceToParkKm,
+      distance_to_mall_km: params.distanceToMallKm,
+      flood_zone_risk:
+        params.floodZoneRisk != null ? FLOOD_RISK_TO_SCORE[params.floodZoneRisk] ?? 0 : undefined,
+      rooms: params.bedrooms ?? propertyData?.bedrooms,
+      total_floors: params.floors ?? propertyData?.floors,
+      building_age_years: yearBuilt != null ? Math.max(0, now.getFullYear() - yearBuilt) : undefined,
+      has_elevator: params.hasElevator,
+      has_parking: params.hasParking,
+      has_pool: params.hasPool,
+      has_legal_paper: params.hasLegalPaper ?? propertyData?.hasLegalPaper ?? true,
+      month: now.getMonth() + 1,
+      quarter: Math.floor(now.getMonth() / 3) + 1,
+      is_year_end: now.getMonth() >= 9,
+    };
+
+    const aiResult = await this.aiClient.predictV2(v2Request);
+
+    let comparables: Comparable[] = [];
+    try {
+      if (params.propertyId) {
+        comparables = await this.fallback.getComparables(params.propertyId, 2000);
+      }
+    } catch {
+      // Supplementary — don't fail
+    }
+
+    return {
+      estimatedPrice: Math.round(aiResult.estimated_price_vnd).toString(),
+      confidence: aiResult.confidence,
+      pricePerM2: Math.round(aiResult.price_per_m2_vnd),
+      comparables,
+      modelVersion: aiResult.model_version ?? 'ai-service-v2',
+    };
+  }
+
   private async getPropertyDetails(propertyId: string) {
     const row = await this.prisma.property.findUnique({
       where: { id: propertyId },