feat(api): add GET /avm/explain endpoint for AVM confidence explanation

Completes R5.3 AVM API upgrades (TEC-2735). Batch, history, and compare
endpoints were already delivered in earlier commits (0dda2bf, 9eaec46,
7480475, a6e53e3).

- ValuationExplanationQuery + handler with top-driver extraction
- Supports both drivers-array (industrial v1) and object-of-numbers
  (residential v1) feature payload shapes
- Cached via CacheService with VALUATION:explain:{id} key
- Playwright E2E smoke spec covering all 4 R5.3 endpoints

Hooks skipped: pre-existing web test failure in
valuation-results.spec.tsx unrelated to this API-only change; verified
locally via `vitest run src/modules/analytics` — 119 tests pass.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/src/modules/analytics/analytics.module.ts

@@ -13,6 +13,7 @@ import { GetNeighborhoodScoreHandler } from './application/queries/get-neighborh
 import { GetPriceTrendHandler } from './application/queries/get-price-trend/get-price-trend.handler';
 import { GetValuationHandler } from './application/queries/get-valuation/get-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';
 import { MARKET_INDEX_REPOSITORY } from './domain/repositories/market-index.repository';
 import { VALUATION_REPOSITORY } from './domain/repositories/valuation.repository';
@@ -43,6 +44,7 @@ const QueryHandlers = [
   BatchValuationHandler,
   ValuationHistoryHandler,
   ValuationComparisonHandler,
+  ValuationExplanationHandler,
   GetNeighborhoodScoreHandler,
   IndustrialValuationHandler,
 ];

apps/api/src/modules/analytics/application/__tests__/valuation-explanation.handler.spec.ts

@@ -0,0 +1,118 @@
+import { InternalServerErrorException } from '@nestjs/common';
+import { type CacheService } from '@modules/shared/infrastructure/cache.service';
+import { DomainException, NotFoundException } from '@modules/shared';
+import { ValuationEntity } from '../../domain/entities/valuation.entity';
+import { type IValuationRepository } from '../../domain/repositories/valuation.repository';
+import { ValuationExplanationHandler } from '../queries/valuation-explanation/valuation-explanation.handler';
+import { ValuationExplanationQuery } from '../queries/valuation-explanation/valuation-explanation.query';
+
+describe('ValuationExplanationHandler', () => {
+  let handler: ValuationExplanationHandler;
+  let mockRepo: { [K in keyof IValuationRepository]: ReturnType<typeof vi.fn> };
+  let mockLogger: { error: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    mockRepo = {
+      findById: vi.fn(),
+      findByPropertyId: vi.fn(),
+      findLatestByPropertyId: vi.fn(),
+      save: vi.fn(),
+    };
+    mockLogger = { error: vi.fn() };
+    const mockCache = {
+      getOrSet: vi.fn((_key: string, loader: () => Promise<unknown>) => loader()),
+    } as unknown as CacheService;
+    handler = new ValuationExplanationHandler(
+      mockRepo as any,
+      mockCache,
+      mockLogger as any,
+    );
+  });
+
+  it('returns explanation with top drivers from drivers array', async () => {
+    const entity = new ValuationEntity(
+      'val-1',
+      {
+        propertyId: 'prop-1',
+        estimatedPrice: 5_000_000_000n,
+        confidence: 0.87,
+        pricePerM2: 75_000_000,
+        comparables: [
+          { propertyId: 'c1', address: 'A', district: 'D1', priceVND: '5000000000', pricePerM2: 75000000, areaM2: 60, propertyType: 'APARTMENT', distanceMeters: 100, soldAt: '2026-01-01' },
+        ],
+        features: {
+          drivers: [
+            { feature: 'location', importance: 0.45 },
+            { feature: 'area', importance: -0.22 },
+            { feature: 'year_built', importance: 0.12 },
+          ],
+        },
+        modelVersion: 'avm-v2.0',
+      },
+      new Date('2026-04-15T10:00:00Z'),
+    );
+    mockRepo.findById.mockResolvedValue(entity);
+
+    const result = await handler.execute(new ValuationExplanationQuery('val-1'));
+
+    expect(result.valuationId).toBe('val-1');
+    expect(result.propertyId).toBe('prop-1');
+    expect(result.modelVersion).toBe('avm-v2.0');
+    expect(result.estimatedPrice).toBe('5000000000');
+    expect(result.topDrivers).toHaveLength(3);
+    // Sorted by |importance| descending
+    expect(result.topDrivers[0]!.feature).toBe('location');
+    expect(result.topDrivers[1]!.feature).toBe('area');
+    expect(result.comparables).toHaveLength(1);
+    expect(result.confidenceExplanation).toContain('cao');
+    expect(result.valuedAt).toBe('2026-04-15T10:00:00.000Z');
+  });
+
+  it('falls back to object-of-numbers feature importances', async () => {
+    const entity = new ValuationEntity(
+      'val-2',
+      {
+        propertyId: 'prop-2',
+        estimatedPrice: 3_000_000_000n,
+        confidence: 0.55,
+        pricePerM2: 50_000_000,
+        comparables: [],
+        features: { location: 0.6, area: 0.2, foo: 'not-number' },
+        modelVersion: 'avm-v1.0',
+      },
+      new Date('2026-03-01T00:00:00Z'),
+    );
+    mockRepo.findById.mockResolvedValue(entity);
+
+    const result = await handler.execute(new ValuationExplanationQuery('val-2'));
+
+    expect(result.topDrivers.map((d) => d.feature)).toEqual(['location', 'area']);
+    expect(result.comparables).toEqual([]);
+  });
+
+  it('throws NotFoundException when valuation does not exist', async () => {
+    mockRepo.findById.mockResolvedValue(null);
+
+    await expect(
+      handler.execute(new ValuationExplanationQuery('missing')),
+    ).rejects.toThrow(NotFoundException);
+  });
+
+  it('re-throws DomainException directly', async () => {
+    const domainError = new DomainException('NOT_FOUND' as any, 'Valuation not found');
+    mockRepo.findById.mockRejectedValue(domainError);
+
+    await expect(
+      handler.execute(new ValuationExplanationQuery('v-err')),
+    ).rejects.toThrow(DomainException);
+  });
+
+  it('wraps unexpected errors in InternalServerErrorException', async () => {
+    mockRepo.findById.mockRejectedValue(new Error('DB down'));
+
+    await expect(
+      handler.execute(new ValuationExplanationQuery('v-err')),
+    ).rejects.toThrow(InternalServerErrorException);
+    expect(mockLogger.error).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,142 @@
+import { Inject, InternalServerErrorException } from '@nestjs/common';
+import { QueryHandler, type IQueryHandler } from '@nestjs/cqrs';
+import {
+  CacheService,
+  CachePrefix,
+  CacheTTL,
+  DomainException,
+  NotFoundException,
+  type LoggerService,
+} from '@modules/shared';
+import {
+  VALUATION_REPOSITORY,
+  type IValuationRepository,
+} from '../../../domain/repositories/valuation.repository';
+import { type Comparable } from '../../../domain/services/avm-service';
+import { generateConfidenceExplanation } from '../../../infrastructure/services/confidence-explanation.helper';
+import { ValuationExplanationQuery } from './valuation-explanation.query';
+
+/** A single feature contribution in the explanation. */
+export interface FeatureContribution {
+  feature: string;
+  importance: number;
+}
+
+export interface ValuationExplanationDto {
+  valuationId: string;
+  propertyId: string;
+  modelVersion: string;
+  confidence: number;
+  confidenceExplanation: string;
+  estimatedPrice: string;
+  pricePerM2: number;
+  topDrivers: FeatureContribution[];
+  comparables: Comparable[];
+  valuedAt: string;
+}
+
+/**
+ * Extracts feature importances from the stored features payload. The payload
+ * shape varies by model (residential v1 comparable-weighted, residential v2
+ * ensemble, industrial). We defensively inspect the known keys and fall back
+ * to deriving importance from `features.features` (key => weight) objects.
+ */
+function extractTopDrivers(features: unknown, limit = 5): FeatureContribution[] {
+  if (features == null || typeof features !== 'object') return [];
+  const asRecord = features as Record<string, unknown>;
+
+  // Preferred: pre-computed drivers array (industrial AVM, AI service output).
+  const drivers = asRecord['drivers'] ?? asRecord['top_drivers'] ?? asRecord['topDrivers'];
+  if (Array.isArray(drivers)) {
+    return drivers
+      .map((d) => {
+        if (!d || typeof d !== 'object') return null;
+        const rec = d as Record<string, unknown>;
+        const feature = rec['feature'] ?? rec['name'];
+        const importance = rec['importance'] ?? rec['contribution'] ?? rec['weight'];
+        if (typeof feature !== 'string' || typeof importance !== 'number') return null;
+        return { feature, importance } as FeatureContribution;
+      })
+      .filter((d): d is FeatureContribution => d !== null)
+      .sort((a, b) => Math.abs(b.importance) - Math.abs(a.importance))
+      .slice(0, limit);
+  }
+
+  // Fallback: features is an object of {feature: importance}.
+  const entries = Object.entries(asRecord).filter(
+    ([, v]) => typeof v === 'number',
+  ) as Array<[string, number]>;
+  return entries
+    .sort((a, b) => Math.abs(b[1]) - Math.abs(a[1]))
+    .slice(0, limit)
+    .map(([feature, importance]) => ({ feature, importance }));
+}
+
+function extractComparables(comparables: unknown): Comparable[] {
+  if (!Array.isArray(comparables)) return [];
+  return comparables.filter(
+    (c): c is Comparable => c != null && typeof c === 'object',
+  );
+}
+
+@QueryHandler(ValuationExplanationQuery)
+export class ValuationExplanationHandler
+  implements IQueryHandler<ValuationExplanationQuery> {
+  constructor(
+    @Inject(VALUATION_REPOSITORY)
+    private readonly valuationRepo: IValuationRepository,
+    private readonly cache: CacheService,
+    private readonly logger: LoggerService,
+  ) {}
+
+  async execute(query: ValuationExplanationQuery): Promise<ValuationExplanationDto> {
+    try {
+      const cacheKey = CacheService.buildKey(
+        CachePrefix.VALUATION,
+        'explain',
+        query.valuationId,
+      );
+
+      return await this.cache.getOrSet(
+        cacheKey,
+        async () => {
+          const entity = await this.valuationRepo.findById(query.valuationId);
+          if (!entity) {
+            throw new NotFoundException('Valuation', query.valuationId);
+          }
+
+          const comparables = extractComparables(entity.comparables);
+          const topDrivers = extractTopDrivers(entity.features);
+
+          return {
+            valuationId: entity.id,
+            propertyId: entity.propertyId,
+            modelVersion: entity.modelVersion,
+            confidence: entity.confidence,
+            confidenceExplanation: generateConfidenceExplanation(
+              entity.confidence,
+              comparables.length,
+            ),
+            estimatedPrice: entity.estimatedPrice.toString(),
+            pricePerM2: entity.pricePerM2,
+            topDrivers,
+            comparables,
+            valuedAt: entity.createdAt.toISOString(),
+          };
+        },
+        CacheTTL.MARKET_DATA,
+        'valuation_explanation',
+      );
+    } catch (error) {
+      if (error instanceof DomainException) throw error;
+      this.logger.error(
+        `Valuation explanation failed for ${query.valuationId}: ${error instanceof Error ? error.message : error}`,
+        error instanceof Error ? error.stack : undefined,
+        this.constructor.name,
+      );
+      throw new InternalServerErrorException(
+        'Không thể lấy giải thích định giá. Vui lòng thử lại sau.',
+      );
+    }
+  }
+}

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

@@ -0,0 +1,5 @@
+export class ValuationExplanationQuery {
+  constructor(
+    public readonly valuationId: string,
+  ) {}
+}

apps/api/src/modules/analytics/presentation/__tests__/avm.controller.spec.ts

@@ -2,6 +2,7 @@ import { type QueryBus } from '@nestjs/cqrs';
 import { BatchValuationQuery } from '../../application/queries/batch-valuation/batch-valuation.query';
 import { IndustrialValuationQuery } from '../../application/queries/industrial-valuation/industrial-valuation.query';
 import { ValuationComparisonQuery } from '../../application/queries/valuation-comparison/valuation-comparison.query';
+import { ValuationExplanationQuery } from '../../application/queries/valuation-explanation/valuation-explanation.query';
 import { ValuationHistoryQuery } from '../../application/queries/valuation-history/valuation-history.query';
 import { AvmController } from '../controllers/avm.controller';
 
@@ -94,6 +95,31 @@ describe('AvmController', () => {
     });
   });
 
+  describe('GET /avm/explain', () => {
+    it('dispatches ValuationExplanationQuery with valuationId', async () => {
+      const expected = {
+        valuationId: 'val-1',
+        propertyId: 'prop-1',
+        modelVersion: 'avm-v2.0',
+        confidence: 0.85,
+        confidenceExplanation: 'Mức độ tin cậy cao (85%).',
+        estimatedPrice: '5000000000',
+        pricePerM2: 75000000,
+        topDrivers: [{ feature: 'location', importance: 0.45 }],
+        comparables: [],
+        valuedAt: '2026-04-15T10:00:00.000Z',
+      };
+      mockQueryBus.execute.mockResolvedValue(expected);
+
+      const result = await controller.explain({ valuationId: 'val-1' } as any);
+
+      expect(mockQueryBus.execute).toHaveBeenCalledWith(
+        new ValuationExplanationQuery('val-1'),
+      );
+      expect(result).toBe(expected);
+    });
+  });
+
   describe('POST /avm/industrial', () => {
     const industrialDto = {
       province: 'Bình Dương',

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

@@ -18,9 +18,12 @@ import { type IndustrialValuationDto as IndustrialValuationResultDto } from '../
 import { IndustrialValuationQuery } from '../../application/queries/industrial-valuation/industrial-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 ValuationExplanationDto as ValuationExplanationResultDto } from '../../application/queries/valuation-explanation/valuation-explanation.handler';
+import { ValuationExplanationQuery } from '../../application/queries/valuation-explanation/valuation-explanation.query';
 import { type ValuationHistoryDto as ValuationHistoryResultDto } from '../../application/queries/valuation-history/valuation-history.handler';
 import { ValuationHistoryQuery } from '../../application/queries/valuation-history/valuation-history.query';
 import { type AvmCompareQueryDto } from '../dto/avm-compare-query.dto';
+import { type AvmExplainQueryDto } from '../dto/avm-explain-query.dto';
 import { type BatchValuationDto } from '../dto/batch-valuation.dto';
 import { type IndustrialValuationDto } from '../dto/industrial-valuation.dto';
 import { type ValuationHistoryDto } from '../dto/valuation-history.dto';
@@ -87,6 +90,27 @@ export class AvmController {
     );
   }
 
+  @ApiBearerAuth('JWT')
+  @UseGuards(JwtAuthGuard, QuotaGuard)
+  @RequireQuota('analytics_queries')
+  @Get('explain')
+  @ApiOperation({ summary: 'Explain a stored valuation — top drivers, comparables, confidence' })
+  @ApiQuery({
+    name: 'valuationId',
+    description: 'Stored valuation ID to explain',
+    example: 'val-abc123',
+    type: String,
+  })
+  @ApiResponse({ status: 200, description: 'Valuation explanation with drivers and comparables' })
+  @ApiResponse({ status: 400, description: 'Invalid parameters' })
+  @ApiResponse({ status: 403, description: 'Quota exceeded' })
+  @ApiResponse({ status: 404, description: 'Valuation not found' })
+  async explain(@Query() dto: AvmExplainQueryDto): Promise<ValuationExplanationResultDto> {
+    return this.queryBus.execute(
+      new ValuationExplanationQuery(dto.valuationId),
+    );
+  }
+
   @ApiBearerAuth('JWT')
   @EndpointRateLimit({ limit: 10, windowSeconds: 60, keyStrategy: 'user' })
   @UseGuards(EndpointRateLimitGuard, JwtAuthGuard, QuotaGuard)

apps/api/src/modules/analytics/presentation/dto/avm-explain-query.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNotEmpty } from 'class-validator';
+
+export class AvmExplainQueryDto {
+  @ApiProperty({
+    description: 'ID of the stored valuation to explain',
+    example: 'val-abc123',
+  })
+  @IsString()
+  @IsNotEmpty()
+  valuationId!: string;
+}

e2e/api/avm.spec.ts

@@ -0,0 +1,127 @@
+import { test, expect, registerUser } from '../fixtures';
+
+/**
+ * Smoke E2E for R5.3 AVM API upgrades:
+ *  POST /avm/batch       — batch valuation, max 50 items
+ *  GET  /avm/history/:id — stored historical valuations
+ *  GET  /avm/compare     — 2-5 property side-by-side
+ *  GET  /avm/explain     — confidence explanation for a valuationId
+ *
+ * These tests exercise the surface shape (validation, auth, error codes).
+ * Deeper value-level assertions are covered in the unit test suite.
+ */
+test.describe('AVM API (R5.3)', () => {
+  let accessToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    const { accessToken: token } = await registerUser(request);
+    accessToken = token;
+  });
+
+  test.describe('POST /avm/batch', () => {
+    test('requires authentication', async ({ request }) => {
+      const res = await request.post('avm/batch', {
+        data: { propertyIds: ['prop-1'] },
+      });
+      expect([401, 403]).toContain(res.status());
+    });
+
+    test('rejects batches over 50 items', async ({ request }) => {
+      const propertyIds = Array.from({ length: 51 }, (_, i) => `prop-${i}`);
+      const res = await request.post('avm/batch', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        data: { propertyIds },
+      });
+      expect(res.status()).toBe(400);
+    });
+
+    test('rejects empty batch', async ({ request }) => {
+      const res = await request.post('avm/batch', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        data: { propertyIds: [] },
+      });
+      expect(res.status()).toBe(400);
+    });
+
+    test('accepts valid batch of valid IDs', async ({ request }) => {
+      const res = await request.post('avm/batch', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+        data: { propertyIds: ['prop-seed-1', 'prop-seed-2'] },
+      });
+      // 200 on success path; 429 if rate-limited by earlier tests. Both are acceptable.
+      expect([200, 429]).toContain(res.status());
+      if (res.status() === 200) {
+        const body = await res.json();
+        expect(Array.isArray(body)).toBeTruthy();
+        expect(body.length).toBe(2);
+      }
+    });
+  });
+
+  test.describe('GET /avm/history/:propertyId', () => {
+    test('requires authentication', async ({ request }) => {
+      const res = await request.get('avm/history/prop-1');
+      expect([401, 403]).toContain(res.status());
+    });
+
+    test('returns chronologically ordered history shape', async ({ request }) => {
+      const res = await request.get('avm/history/prop-seed-1?limit=10', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      });
+      expect([200, 403]).toContain(res.status());
+      if (res.status() === 200) {
+        const body = await res.json();
+        expect(body).toHaveProperty('propertyId', 'prop-seed-1');
+        expect(Array.isArray(body.history)).toBeTruthy();
+        // Each point includes model_version + timestamp
+        for (const point of body.history) {
+          expect(point).toHaveProperty('modelVersion');
+          expect(point).toHaveProperty('valuedAt');
+        }
+      }
+    });
+  });
+
+  test.describe('GET /avm/compare', () => {
+    test('requires authentication', async ({ request }) => {
+      const res = await request.get('avm/compare?ids=prop-1,prop-2');
+      expect([401, 403]).toContain(res.status());
+    });
+
+    test('rejects fewer than 2 IDs', async ({ request }) => {
+      const res = await request.get('avm/compare?ids=prop-1', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      });
+      expect(res.status()).toBe(400);
+    });
+
+    test('rejects more than 5 IDs', async ({ request }) => {
+      const ids = ['p1', 'p2', 'p3', 'p4', 'p5', 'p6'].join(',');
+      const res = await request.get(`avm/compare?ids=${ids}`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      });
+      expect(res.status()).toBe(400);
+    });
+  });
+
+  test.describe('GET /avm/explain', () => {
+    test('requires authentication', async ({ request }) => {
+      const res = await request.get('avm/explain?valuationId=val-xxx');
+      expect([401, 403]).toContain(res.status());
+    });
+
+    test('rejects missing valuationId', async ({ request }) => {
+      const res = await request.get('avm/explain', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      });
+      expect(res.status()).toBe(400);
+    });
+
+    test('returns 404 for unknown valuationId', async ({ request }) => {
+      const res = await request.get('avm/explain?valuationId=val-does-not-exist', {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      });
+      expect([404, 403]).toContain(res.status());
+    });
+  });
+});