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/analytics.module.ts

@@ -12,6 +12,7 @@ import { GetMarketReportHandler } from './application/queries/get-market-report/
 import { GetNeighborhoodScoreHandler } from './application/queries/get-neighborhood-score/get-neighborhood-score.handler';
 import { GetPriceTrendHandler } from './application/queries/get-price-trend/get-price-trend.handler';
 import { GetValuationHandler } from './application/queries/get-valuation/get-valuation.handler';
+import { PredictValuationHandler } from './application/queries/predict-valuation/predict-valuation.handler';
 import { ValuationComparisonHandler } from './application/queries/valuation-comparison/valuation-comparison.handler';
 import { ValuationExplanationHandler } from './application/queries/valuation-explanation/valuation-explanation.handler';
 import { ValuationHistoryHandler } from './application/queries/valuation-history/valuation-history.handler';
@@ -44,6 +45,7 @@ const QueryHandlers = [
   GetPriceTrendHandler,
   GetDistrictStatsHandler,
   GetValuationHandler,
+  PredictValuationHandler,
   BatchValuationHandler,
   ValuationHistoryHandler,
   ValuationComparisonHandler,

apps/api/src/modules/analytics/application/queries/predict-valuation/predict-valuation.handler.ts

@@ -0,0 +1,62 @@
+import { Inject, InternalServerErrorException } from '@nestjs/common';
+import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import { DomainException, LoggerService } from '@modules/shared';
+import {
+  AVM_SERVICE,
+  type IAVMService,
+  type ValuationResult,
+} from '../../../domain/services/avm-service';
+import { PredictValuationQuery } from './predict-valuation.query';
+
+export type PredictValuationDto = ValuationResult;
+
+@QueryHandler(PredictValuationQuery)
+export class PredictValuationHandler implements IQueryHandler<PredictValuationQuery> {
+  constructor(
+    @Inject(AVM_SERVICE) private readonly avmService: IAVMService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(query: PredictValuationQuery): Promise<PredictValuationDto> {
+    try {
+      return await this.avmService.estimateValue({
+        propertyId: undefined,
+        propertyType: query.propertyType,
+        areaM2: query.area,
+        district: query.district,
+        city: query.city,
+        bedrooms: query.bedrooms,
+        bathrooms: query.bathrooms,
+        floors: query.floors,
+        frontage: query.frontage,
+        roadWidth: query.roadWidth,
+        yearBuilt: query.yearBuilt,
+        hasLegalPaper: query.hasLegalPaper,
+        latitude: query.latitude,
+        longitude: query.longitude,
+        projectId: query.projectId,
+        imageUrl: query.imageUrl,
+        description: query.description,
+        deepAnalysis: query.deepAnalysis,
+        useV2: query.useV2,
+        distanceToHospitalKm: query.distanceToHospitalKm,
+        distanceToParkKm: query.distanceToParkKm,
+        distanceToMallKm: query.distanceToMallKm,
+        floodZoneRisk: query.floodZoneRisk,
+        hasElevator: query.hasElevator,
+        hasParking: query.hasParking,
+        hasPool: query.hasPool,
+      });
+    } catch (error) {
+      if (error instanceof DomainException) throw error;
+      this.logger.error(
+        `Predict valuation failed: ${error instanceof Error ? error.message : error}`,
+        error instanceof Error ? error.stack : undefined,
+        this.constructor.name,
+      );
+      throw new InternalServerErrorException(
+        'Không thể định giá bất động sản. Vui lòng thử lại sau.',
+      );
+    }
+  }
+}

apps/api/src/modules/analytics/application/queries/predict-valuation/predict-valuation.query.ts

@@ -0,0 +1,33 @@
+import { type PropertyType } from '@prisma/client';
+import { type FloodZoneRisk } from '../../../domain/services/avm-service';
+
+export class PredictValuationQuery {
+  constructor(
+    public readonly userId: string | null,
+    public readonly propertyType: PropertyType,
+    public readonly area: number,
+    public readonly district: string,
+    public readonly city: string,
+    public readonly bedrooms?: number,
+    public readonly bathrooms?: number,
+    public readonly floors?: number,
+    public readonly frontage?: number,
+    public readonly roadWidth?: number,
+    public readonly yearBuilt?: number,
+    public readonly hasLegalPaper?: boolean,
+    public readonly latitude?: number,
+    public readonly longitude?: number,
+    public readonly projectId?: string,
+    public readonly imageUrl?: string,
+    public readonly description?: string,
+    public readonly deepAnalysis?: boolean,
+    public readonly useV2?: boolean,
+    public readonly distanceToHospitalKm?: number,
+    public readonly distanceToParkKm?: number,
+    public readonly distanceToMallKm?: number,
+    public readonly floodZoneRisk?: FloodZoneRisk,
+    public readonly hasElevator?: boolean,
+    public readonly hasParking?: boolean,
+    public readonly hasPool?: boolean,
+  ) {}
+}

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

@@ -2,6 +2,8 @@ import { type PropertyType } from '@prisma/client';
 
 export const AVM_SERVICE = Symbol('AVM_SERVICE');
 
+export type FloodZoneRisk = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
+
 export interface AVMParams {
   propertyId?: string;
   latitude?: number;
@@ -11,6 +13,30 @@ export interface AVMParams {
   yearBuilt?: number;
   floor?: number;
   totalFloors?: number;
+
+  // ── Optional inline descriptors (used when no propertyId is given) ──
+  district?: string;
+  city?: string;
+  bedrooms?: number;
+  bathrooms?: number;
+  floors?: number;
+  frontage?: number;
+  roadWidth?: number;
+  hasLegalPaper?: boolean;
+  projectId?: string;
+  imageUrl?: string;
+  description?: string;
+  deepAnalysis?: boolean;
+
+  // ── AVM v2 features ────────────────────────────────────────────────
+  useV2?: boolean;
+  distanceToHospitalKm?: number;
+  distanceToParkKm?: number;
+  distanceToMallKm?: number;
+  floodZoneRisk?: FloodZoneRisk;
+  hasElevator?: boolean;
+  hasParking?: boolean;
+  hasPool?: boolean;
 }
 
 export interface Comparable {

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 },

apps/api/src/modules/analytics/presentation/controllers/analytics.controller.ts

@@ -25,6 +25,8 @@ import { type PriceTrendDto } from '../../application/queries/get-price-trend/ge
 import { GetPriceTrendQuery } from '../../application/queries/get-price-trend/get-price-trend.query';
 import { type ValuationDto } from '../../application/queries/get-valuation/get-valuation.handler';
 import { GetValuationQuery } from '../../application/queries/get-valuation/get-valuation.query';
+import { type PredictValuationDto } from '../../application/queries/predict-valuation/predict-valuation.handler';
+import { PredictValuationQuery } from '../../application/queries/predict-valuation/predict-valuation.query';
 import { type ValuationComparisonDto as ValuationComparisonResultDto } from '../../application/queries/valuation-comparison/valuation-comparison.handler';
 import { ValuationComparisonQuery } from '../../application/queries/valuation-comparison/valuation-comparison.query';
 import { type ValuationHistoryDto as ValuationHistoryResultDto } from '../../application/queries/valuation-history/valuation-history.handler';
@@ -36,6 +38,7 @@ import { GetHeatmapDto } from '../dto/get-heatmap.dto';
 import { GetMarketReportDto } from '../dto/get-market-report.dto';
 import { GetPriceTrendDto } from '../dto/get-price-trend.dto';
 import { GetValuationDto } from '../dto/get-valuation.dto';
+import { PredictValuationDto as PredictValuationBodyDto } from '../dto/predict-valuation.dto';
 import { ValuationComparisonDto } from '../dto/valuation-comparison.dto';
 import { ValuationHistoryDto } from '../dto/valuation-history.dto';
 
@@ -112,6 +115,55 @@ export class AnalyticsController {
     );
   }
 
+  @ApiBearerAuth('JWT')
+  @EndpointRateLimit({ limit: 10, windowSeconds: 60, keyStrategy: 'user' })
+  @UseGuards(EndpointRateLimitGuard, JwtAuthGuard, QuotaGuard)
+  @RequireQuota('analytics_queries')
+  @Post('valuation')
+  @ApiOperation({
+    summary: 'Định giá BĐS (AVM v1/v2) từ form nhập tay',
+    description:
+      'Nhận đặc trưng BĐS qua body và trả về ước tính giá. `useV2=true` dùng mô hình ensemble v2 với các trường khoảng cách hạ tầng + tiện nghi + nguy cơ ngập.',
+  })
+  @ApiResponse({ status: 200, description: 'Valuation estimate retrieved' })
+  @ApiResponse({ status: 400, description: 'Invalid parameters' })
+  @ApiResponse({ status: 401, description: 'Chưa xác thực' })
+  @ApiResponse({ status: 403, description: 'Quota exceeded' })
+  @ApiResponse({ status: 429, description: 'Rate limit exceeded' })
+  @ApiResponse({ status: 503, description: 'Dịch vụ AI tạm thời không khả dụng' })
+  async predictValuation(@Body() dto: PredictValuationBodyDto): Promise<PredictValuationDto> {
+    return this.queryBus.execute(
+      new PredictValuationQuery(
+        null,
+        dto.propertyType,
+        dto.area,
+        dto.district,
+        dto.city,
+        dto.bedrooms,
+        dto.bathrooms,
+        dto.floors,
+        dto.frontage,
+        dto.roadWidth,
+        dto.yearBuilt,
+        dto.hasLegalPaper,
+        dto.latitude,
+        dto.longitude,
+        dto.projectId,
+        dto.imageUrl,
+        dto.description,
+        dto.deepAnalysis,
+        dto.useV2,
+        dto.distanceToHospitalKm,
+        dto.distanceToParkKm,
+        dto.distanceToMallKm,
+        dto.floodZoneRisk,
+        dto.hasElevator,
+        dto.hasParking,
+        dto.hasPool,
+      ),
+    );
+  }
+
   @ApiBearerAuth('JWT')
   @EndpointRateLimit({ limit: 10, windowSeconds: 60, keyStrategy: 'user' })
   @UseGuards(EndpointRateLimitGuard, JwtAuthGuard, QuotaGuard)

apps/api/src/modules/analytics/presentation/dto/predict-valuation.dto.ts

@@ -0,0 +1,174 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { PropertyType } from '@prisma/client';
+import { Type } from 'class-transformer';
+import {
+  IsBoolean,
+  IsEnum,
+  IsIn,
+  IsInt,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Max,
+  MaxLength,
+  Min,
+} from 'class-validator';
+
+export type FloodZoneRisk = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';
+
+export const FLOOD_ZONE_RISK_VALUES: FloodZoneRisk[] = ['NONE', 'LOW', 'MEDIUM', 'HIGH'];
+
+export class PredictValuationDto {
+  // ── Core v1 fields ─────────────────────────────────────────────────
+  @ApiProperty({ enum: PropertyType, description: 'Loại bất động sản' })
+  @IsEnum(PropertyType)
+  propertyType!: PropertyType;
+
+  @ApiProperty({ description: 'Diện tích (m²)', example: 75 })
+  @IsNumber()
+  @Min(1)
+  @Type(() => Number)
+  area!: number;
+
+  @ApiProperty({ description: 'Quận/Huyện', example: 'Quận 1' })
+  @IsString()
+  district!: string;
+
+  @ApiProperty({ description: 'Tỉnh/Thành phố', example: 'Hồ Chí Minh' })
+  @IsString()
+  city!: string;
+
+  @ApiPropertyOptional({ description: 'Số phòng ngủ', example: 2 })
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(20)
+  @Type(() => Number)
+  bedrooms?: number;
+
+  @ApiPropertyOptional({ description: 'Số phòng tắm' })
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(20)
+  @Type(() => Number)
+  bathrooms?: number;
+
+  @ApiPropertyOptional({ description: 'Số tầng' })
+  @IsOptional()
+  @IsInt()
+  @Min(0)
+  @Max(200)
+  @Type(() => Number)
+  floors?: number;
+
+  @ApiPropertyOptional({ description: 'Mặt tiền (m)' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  frontage?: number;
+
+  @ApiPropertyOptional({ description: 'Độ rộng đường trước nhà (m)' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  roadWidth?: number;
+
+  @ApiPropertyOptional({ description: 'Năm xây' })
+  @IsOptional()
+  @IsInt()
+  @Min(1900)
+  @Max(2100)
+  @Type(() => Number)
+  yearBuilt?: number;
+
+  @ApiPropertyOptional({ description: 'Có giấy tờ pháp lý đầy đủ' })
+  @IsOptional()
+  @IsBoolean()
+  hasLegalPaper?: boolean;
+
+  @ApiPropertyOptional({ description: 'Vĩ độ' })
+  @IsOptional()
+  @IsNumber()
+  @Type(() => Number)
+  latitude?: number;
+
+  @ApiPropertyOptional({ description: 'Kinh độ' })
+  @IsOptional()
+  @IsNumber()
+  @Type(() => Number)
+  longitude?: number;
+
+  @ApiPropertyOptional({ description: 'ID dự án (nếu thuộc dự án)' })
+  @IsOptional()
+  @IsString()
+  projectId?: string;
+
+  @ApiPropertyOptional({ description: 'URL ảnh BĐS để phân tích' })
+  @IsOptional()
+  @IsString()
+  imageUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Mô tả bổ sung' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  description?: string;
+
+  @ApiPropertyOptional({ description: 'Bật phân tích chuyên sâu (Claude)' })
+  @IsOptional()
+  @IsBoolean()
+  deepAnalysis?: boolean;
+
+  // ── AVM v2 fields ──────────────────────────────────────────────────
+  @ApiPropertyOptional({ description: 'Dùng mô hình AVM v2 (ensemble + đặc trưng mở rộng)' })
+  @IsOptional()
+  @IsBoolean()
+  useV2?: boolean;
+
+  @ApiPropertyOptional({ description: 'Khoảng cách tới bệnh viện (km)' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  distanceToHospitalKm?: number;
+
+  @ApiPropertyOptional({ description: 'Khoảng cách tới công viên (km)' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  distanceToParkKm?: number;
+
+  @ApiPropertyOptional({ description: 'Khoảng cách tới trung tâm thương mại (km)' })
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  @Type(() => Number)
+  distanceToMallKm?: number;
+
+  @ApiPropertyOptional({
+    enum: FLOOD_ZONE_RISK_VALUES,
+    description: 'Mức độ nguy cơ ngập lụt',
+  })
+  @IsOptional()
+  @IsIn(FLOOD_ZONE_RISK_VALUES)
+  floodZoneRisk?: FloodZoneRisk;
+
+  @ApiPropertyOptional({ description: 'Có thang máy' })
+  @IsOptional()
+  @IsBoolean()
+  hasElevator?: boolean;
+
+  @ApiPropertyOptional({ description: 'Có chỗ đậu xe' })
+  @IsOptional()
+  @IsBoolean()
+  hasParking?: boolean;
+
+  @ApiPropertyOptional({ description: 'Có hồ bơi' })
+  @IsOptional()
+  @IsBoolean()
+  hasPool?: boolean;
+}