real estate

# valoswiss-real-estate (32°)

**Macro-categoria**: 🏠 DOMINI SINGOLI
**Scope**: Real estate valuation per UHNW client portfolio — residenziale, commerciale, terreni
**Born**: 2026-05-03 (V20 — 3-Point Registration completa)
**Owner downstream**: ADVISOR · FAMILY_OFFICE_PRINCIPAL · SUPERVISOR/ADMIN (cross-tenant real estate dashboard)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Module NestJS presente**
   ```bash
   ls apps/api/src/modules/real-estate/
   ```
   Deve esistere almeno: `real-estate.module.ts`, `real-estate.controller.ts`, `real-estate.service.ts`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/real-estate/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ status:'ok', propertyCount:N, pendingValuations:M }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che le 4 model `Property` / `PropertyValuation` / `PropertyComp` / `PropertyRental` + enum `PropertyTypeEnum` / `PropertyStatusEnum` / `ValuationMethodEnum` siano applicati.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"realEstate": true` subito dopo `macroEconomic`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'realEstate'` in `defaultModules` per `ADVISOR` + `RELATIONSHIP_MANAGER` + `FAMILY_OFFICE_PRINCIPAL` + `SUPERVISOR` + `ADMIN`.
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `realEstate` con `sidebarSection: 'PATRIMONIO'`, `requiredRole: 'ADVISOR'`, `personaHint: 'real-estate'`, icon `🏠`.
8. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`.

Se uno qualunque dei 7 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Repos e fonti dati di riferimento

| Source | Repo / API | Uso |
|--------|------------|-----|
| **brightdata/real-estate-ai-agent** | Bright Data (bright_data) scraping + AI extraction | Property listing extraction da portali web italiani/svizzeri/UK; structured data JSON da HTML grezzo |
| **AleksNeStu/ai-real-estate-assistant** | RAG + LLM pipeline su real estate data | Pattern RAG per query naturale su comparable database; embedding properità + semantic search |
| **Zillow API (ref)** | Zillow API (zws-id) — US reference only | Metodologia AVM (Zestimate model conceptual reference); cap rate calculation patterns |
| **Idealista API** | `api.idealista.com/3.5/` | CH/ES/IT/PT listing search; comparable sales data IT mercato immobiliare |
| **Immoscout24 ref** | Immoscout24 (`immoscout24.ch`) | CH cantons comparable; referenza prezzi immobili svizzeri (Zürich, Genève, Zug, Bern, Basel) |
| **Comparable Sales DB** | Interno ValoSwiss — `PropertyComp` | SSOT dei comparabili verificati manualmente da ADVISOR + estratti da browser-agent |

### 1.2 Tipi di proprietà gestiti

| Tipo | PropertyTypeEnum | Geografie |
|------|-----------------|-----------|
| **Residenziale** | `RESIDENTIAL` | CH, IT, UK, Monaco, Côte d'Azur |
| **Commerciale** | `COMMERCIAL` | CH (Zürich CBD, Genève), IT (Milano, Roma) |
| **Uffici** | `OFFICE` | CH, UK (Londra City/West End) |
| **Retail** | `RETAIL` | CH high street, IT centro storico |
| **Industriale/Logistica** | `INDUSTRIAL` | CH periurbano, IT Nord |
| **Terreno edificabile** | `LAND` | CH cantonale, Côte d'Azur, IT agro |
| **Hotel / Hospitality** | `HOSPITALITY` | Monaco, Côte d'Azur, CH resort |
| **Agricultural** | `AGRICULTURAL` | IT Toscana/Umbria, CH Ticino |

### 1.3 Focus geografico per metodo di valutazione

**Switzerland (CH cantons)**
- Cantoni principali: ZH, GE, ZG, BS, BE, TI, VD, LU
- Dati Immoscout24 + Homegate.ch (via browser-agent)
- Metodo prevalente: AVM hedonic + CMA
- Benchmark: Wüest Partner Index (reference), SIX Real Estate Index
- Cap rate tipico residenziale: 2.5%-4.5% netto canton-dependent
- Cap rate uffici Zürich CBD: 3.0%-4.0%

**Italia**
- Zone: Milano (centro/citylife/porta nuova), Roma (centro storico/parioli), Firenze, Costa Amalfitana, Toscana, Umbria, Sardegna (Costa Smeralda), Lago di Como
- Dati Idealista IT + Immobiliare.it (via browser-agent)
- Metodo prevalente: CMA + hedonic regression (€/mq base)
- Cap rate residenziale lusso: 2.5%-3.5%
- Fattori PST (piano, stato, tipologia) + view premium

**UK**
- Zone: Londra (Mayfair/Belgravia/Knightsbridge/Kensington/Chelsea), Surrey countryside
- Dati Zoopla/Rightmove (via browser-agent) + Land Registry (public)
- Metodo prevalente: CMA + RICS-aligned (Royal Institution of Chartered Surveyors)
- Cap rate residenziale prime: 2.0%-3.5% PCM
- Stamp Duty Land Tax (SDLT) impatta rendimento netto

**Monaco**
- Tutto il principato — micro-mercato altissima liquidità + prezzi primari EU
- Prezzi: €40,000-€100,000+ /mq per residenziale premium
- Metodo: puro CMA (pochissime transazioni, ogni comp pesa molto)
- Cap rate: 1.5%-2.5% (domanda > offerta strutturale)

**Côte d'Azur (FR)**
- Zone: Nice, Cannes, Antibes, Saint-Tropez, Cap Ferrat, Èze, Menton
- Dati BIENIMMO + SeLoger (via browser-agent)
- Metodo: hedonic (sea-view premium, étage, état general) + CMA
- Stagionalità: valore estivo vs invernale (differenziale 10%-20%)

### 1.4 Metodologie di valutazione

**CMA — Comparable Market Analysis**
- Selezione comparabili: raggio geografico (default 500m residenziale, 2km commerciale), tipo immobile simile, transatti negli ultimi 24 mesi
- Aggiustamenti standard: superficie (€/mq delta), piano, garage/box, stato conservativo, vista, esposizione, anno costruzione
- Output: `adjustedPricePerSqm` + `valueRange` (min/max ±15%) + `pointEstimate`
- Fonte comps: `PropertyComp` DB interno + integrazione browser-agent per comps recenti

**Hedonic Regression Model**
- Features: superficie lorda (mq), superficie netta, numero locali, bagni, piano (su N piani), anno costruzione, classe energetica, garage (0/1/2), terrazzo/giardino flag, vista (0-3 score), stato (1-5 score), zona macro, distanza centro (km)
- Training: dataset comps verificati per geography+type (min 50 obs per modello)
- Library: `sklearn.LinearRegression` (base) + `sklearn.GradientBoostingRegressor` (ensemble)
- Output: `hedonicEstimate` + `featureImportance[]` + `R2_score` + `RMSE_pct`

**AVM — Automated Valuation Model**
- Ensemble: media pesata CMA (peso 0.5) + hedonic (peso 0.3) + income approach (peso 0.2 se rental data disponibile)
- Confidence score: basso (<0.6) se <3 comps, medio (0.6-0.8) se 3-7 comps, alto (>0.8) se >7 comps + hedonic R2>0.7
- Output: `avmValue` + `confidenceScore` + `confidenceBand` + `methodBreakdown[]`

**Income Approach (yield/cap rate)**
- Cap rate = NOI / PropertyValue
- NOI = Gross Rental Income × (1 - VacancyRate) - OperatingExpenses
- Gross Rental Income: da `PropertyRental` records o stima da comparable rentals
- OperatingExpenses tipici: manutenzione 1.5%/anno, gestione 5-8% NRI, assicurazione 0.2%, IMU/TASI (IT) o ICI (CH) locali
- Rental yield projection: 5/10/20 anni con growth assumption da macro indicators (CPI + local demand)

---

## §2 · Pattern di codice

### 2.1 NestJS Controller

```typescript
// apps/api/src/modules/real-estate/real-estate.controller.ts
@Controller('real-estate')
@UseGuards(JwtAuthGuard, RolesGuard)
export class RealEstateController {
  constructor(private readonly realEstateService: RealEstateService) {}

  @Get('health')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async health() {
    const count = await this.realEstateService.countProperties();
    return { status: 'ok', propertyCount: count.total, pendingValuations: count.pending };
  }

  @Get('properties')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'FAMILY_OFFICE_PRINCIPAL', 'SUPERVISOR', 'ADMIN')
  async listProperties(
    @Query('clientId') clientId?: string,
    @Query('portfolioId') portfolioId?: string,
    @Query('type') type?: string,
    @Query('country') country?: string,
    @Query('page') page = '1',
    @Query('pageSize') pageSize = '20',
  ) {
    return this.realEstateService.listProperties({
      clientId, portfolioId, type, country,
      page: parseInt(page), pageSize: parseInt(pageSize),
    });
  }

  @Get('properties/:id')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'FAMILY_OFFICE_PRINCIPAL', 'SUPERVISOR', 'ADMIN')
  async getProperty(@Param('id') id: string) {
    return this.realEstateService.getPropertyDetail(id);
  }

  @Post('properties')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async createProperty(@Body() dto: CreatePropertyDto, @Request() req: any) {
    return this.realEstateService.createProperty(dto, req.user?.id);
  }

  @Patch('properties/:id')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async updateProperty(
    @Param('id') id: string,
    @Body() dto: UpdatePropertyDto,
    @Request() req: any,
  ) {
    return this.realEstateService.updateProperty(id, dto, req.user?.id);
  }

  @Post('properties/:id/valuation')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async triggerValuation(
    @Param('id') id: string,
    @Body() dto: TriggerValuationDto,
    @Request() req: any,
  ) {
    return this.realEstateService.triggerValuation(id, dto.method, req.user?.id);
  }

  @Get('properties/:id/valuations')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'FAMILY_OFFICE_PRINCIPAL', 'SUPERVISOR', 'ADMIN')
  async getValuationHistory(@Param('id') id: string) {
    return this.realEstateService.getValuationHistory(id);
  }

  @Get('properties/:id/comps')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async getComparables(@Param('id') id: string, @Query('radiusKm') radiusKm = '0.5') {
    return this.realEstateService.findComparables(id, parseFloat(radiusKm));
  }

  @Post('properties/:id/comps')
  @Roles('ADVISOR', 'SUPERVISOR', 'ADMIN')
  async addComparable(@Param('id') id: string, @Body() dto: AddCompDto) {
    return this.realEstateService.addComparable(id, dto);
  }

  @Get('properties/:id/rental-projection')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'FAMILY_OFFICE_PRINCIPAL', 'SUPERVISOR', 'ADMIN')
  async getRentalProjection(
    @Param('id') id: string,
    @Query('years') years = '10',
    @Query('growthRate') growthRate = '0.02',
  ) {
    return this.realEstateService.getRentalProjection(id, parseInt(years), parseFloat(growthRate));
  }

  @Get('portfolio-summary')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'FAMILY_OFFICE_PRINCIPAL', 'SUPERVISOR', 'ADMIN')
  async getPortfolioSummary(@Query('clientId') clientId: string, @Query('tenantSlug') tenantSlug: string) {
    return this.realEstateService.getPortfolioSummary(clientId, tenantSlug);
  }
}
```

### 2.2 NestJS Service — facade + AVM orchestration

```typescript
// apps/api/src/modules/real-estate/real-estate.service.ts
@Injectable()
export class RealEstateService {
  private readonly logger = new Logger(RealEstateService.name);

  constructor(
    @Optional() private readonly prisma: TenantPrismaService,
    private readonly valuationService: PropertyValuationService,
    private readonly cmaService: CmaService,
    private readonly incomeService: RentalIncomeService,
  ) {}

  async countProperties() {
    // Getter espliciti Wave 1.6 — NON usare "legacy cast as-any"
    const [total, pending] = await Promise.all([
      this.prisma.property.count({ where: { deletedAt: null } }),
      this.prisma.propertyValuation.count({ where: { status: 'PENDING' } }),
    ]);
    return { total, pending };
  }

  async listProperties(filters: ListPropertiesFilters) {
    const where: Prisma.PropertyWhereInput = { deletedAt: null };
    if (filters.clientId) where.clientId = filters.clientId;
    if (filters.portfolioId) where.portfolioId = filt

…[truncato — apri il file MD per testo completo]