@horizon-framework/api-nextjs-docs 2.3.0

package/docs/SEARCH_ENGINE_API.md

@@ -0,0 +1,1038 @@
+# Search Engine API - Motor Genérico de Busca
+
+> **Motor de busca reutilizável** que funciona IDENTICAMENTE para qualquer entidade.
+>
+> **Implementado atualmente em:**
+> - `Property` (Imóveis) → `/api/property/search`
+>
+> **Futuramente:**
+> - 🔜 `Broker` (Corretores) → `/api/broker/search`
+> - 🔜 `Condominium` (Condomínios) → `/api/condominium/search`
+> - 🔜 Qualquer outra entidade...
+>
+> **A estrutura de request/response é IDÊNTICA** - só muda o endpoint e os campos disponíveis.
+
+---
+
+## Quick Decision Tree
+
+```
+Preciso de...
+├─ Scroll infinito (mobile/feed)? → CURSOR pagination
+├─ Botões de página (1, 2, 3...)? → OFFSET pagination
+├─ Filtros checkbox (múltipla seleção)? → FACETS com operator='or'
+├─ Filtros hierárquicos (intersecção)? → FACETS com operator='and'
+└─ Apenas contagem rápida? → meta: {}
+```
+
+---
+
+## CURSOR vs OFFSET - DECISÃO CRÍTICA
+
+### **Como a API detecta o modo?**
+
+```typescript
+// CURSOR MODE (infinite scroll)
+{
+  list: {
+    limit: 20,
+    // SEM 'page' = CURSOR MODE
+    cursor: "123"  // opcional - só na 2ª+ requisição
+  }
+}
+
+// OFFSET MODE (paginação tradicional)
+{
+  list: {
+    page: 1,      // COM 'page' = OFFSET MODE
+    limit: 20
+  }
+}
+```
+
+**Regra:** `Se request.list.page === undefined → CURSOR mode`
+
+### **Comparação Rápida**
+
+| Feature | CURSOR | OFFSET |
+|---------|---------|---------|
+| **Use quando** | Scroll infinito, feeds | Botões de página (1, 2, 3) |
+| **Performance** | Excelente | Degrada com páginas altas |
+| **Request** | `{ limit, cursor }` | `{ page, limit }` |
+| **Response** | `{ nextCursor, hasNextPage }` | `{ page, total, totalPages, hasNextPage }` |
+| **Vantagens** | Rápido, consistente | Pode pular páginas, mostra total |
+| **Desvantagens** | Não mostra total, só avança | Lento em páginas altas (ex: página 100) |
+
+---
+
+## SCROLL INFINITO (Cursor-based Pagination)
+
+### **1ª Requisição (inicial)**
+
+```json
+POST /api/property/search
+{
+  "filters": {
+    "tipo": "Apartamento"
+  },
+  "list": {
+    "limit": 20
+    // NÃO enviar 'page'
+    // NÃO enviar 'cursor' na primeira vez
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "results": {
+    "list": {
+      "data": [
+        { "id": 101, "title": "Apto 1..." },
+        { "id": 102, "title": "Apto 2..." },
+        // ... 18 mais
+        { "id": 120, "title": "Apto 20..." }  // ← último item
+      ],
+      "meta": {
+        "limit": 20,
+        "hasNextPage": true,
+        "nextCursor": 120  // ← ID do último item
+      }
+    }
+  }
+}
+```
+
+### **2ª+ Requisições (scroll)**
+
+```json
+POST /api/property/search
+{
+  "filters": {
+    "tipo": "Apartamento"  // MESMOS filtros
+  },
+  "list": {
+    "limit": 20,
+    "cursor": 120  // ← nextCursor da resposta anterior
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "results": {
+    "list": {
+      "data": [
+        { "id": 121, "title": "Apto 21..." },
+        // ... mais 19
+        { "id": 140, "title": "Apto 40..." }
+      ],
+      "meta": {
+        "limit": 20,
+        "hasNextPage": true,
+        "nextCursor": 140  // ← novo cursor
+      }
+    }
+  }
+}
+```
+
+### **Última Requisição (fim dos dados)**
+
+```json
+{
+  "results": {
+    "list": {
+      "data": [
+        { "id": 141, "title": "Apto 41..." },
+        { "id": 142, "title": "Apto 42..." }  // só 2 itens restantes
+      ],
+      "meta": {
+        "limit": 20,
+        "hasNextPage": false,  // ← SEM próxima página
+        "nextCursor": undefined  // ← SEM cursor
+      }
+    }
+  }
+}
+```
+
+### **Implementação Frontend - Checklist**
+
+```typescript
+// Estado
+const [items, setItems] = useState([]);
+const [cursor, setCursor] = useState(undefined);
+const [hasMore, setHasMore] = useState(true);
+
+// Primeira carga
+async function loadInitial() {
+  const response = await fetch('/api/property/search', {
+    method: 'POST',
+    body: JSON.stringify({
+      filters: { tipo: "Apartamento" },
+      list: { limit: 20 }  // SEM cursor, SEM page
+    })
+  });
+
+  const data = await response.json();
+  setItems(data.results.list.data);
+  setCursor(data.results.list.meta.nextCursor);
+  setHasMore(data.results.list.meta.hasNextPage);
+}
+
+// Scroll infinito
+async function loadMore() {
+  if (!hasMore) return;
+
+  const response = await fetch('/api/property/search', {
+    method: 'POST',
+    body: JSON.stringify({
+      filters: { tipo: "Apartamento" },  // MESMOS filtros
+      list: {
+        limit: 20,
+        cursor: cursor  // ← cursor da última resposta
+      }
+    })
+  });
+
+  const data = await response.json();
+  setItems(prev => [...prev, ...data.results.list.data]);  // append
+  setCursor(data.results.list.meta.nextCursor);
+  setHasMore(data.results.list.meta.hasNextPage);
+}
+
+// Quando filtros mudam - RESETAR
+function onFiltersChange(newFilters) {
+  setItems([]);
+  setCursor(undefined);  // ← CRÍTICO: resetar cursor
+  setHasMore(true);
+  // carregar com novos filtros
+}
+```
+
+### **ERROS COMUNS - Scroll Infinito**
+
+#### **Erro 1: Enviando `page` junto com `cursor`**
+```json
+// ERRADO
+{
+  "list": {
+    "page": 1,      // ← Remove isso!
+    "cursor": 120
+  }
+}
+
+// CORRETO
+{
+  "list": {
+    "cursor": 120   // Só cursor
+  }
+}
+```
+
+#### **Erro 2: Não resetar cursor ao mudar filtros**
+```typescript
+// ERRADO - vai trazer dados errados
+function onFilterChange() {
+  // cursor ainda tem valor 120 dos filtros antigos!
+  loadMore();  // Dados misturados
+}
+
+// CORRETO
+function onFilterChange() {
+  setCursor(undefined);  // Reset
+  setItems([]);
+  loadInitial();  // Nova busca do zero
+}
+```
+
+#### **Erro 3: Cursor na primeira requisição**
+```json
+// ERRADO
+{
+  "list": {
+    "cursor": null  // ← Não enviar
+  }
+}
+
+// CORRETO - primeira vez
+{
+  "list": {
+    "limit": 20
+    // sem cursor
+  }
+}
+```
+
+---
+
+## PAGINAÇÃO TRADICIONAL (Offset-based)
+
+### **Request**
+```json
+POST /api/property/search
+{
+  "filters": {
+    "tipo": "Casa"
+  },
+  "list": {
+    "page": 2,      // ← Presença de 'page' ativa OFFSET mode
+    "limit": 20
+  }
+}
+```
+
+### **Response**
+```json
+{
+  "results": {
+    "list": {
+      "data": [...],
+      "meta": {
+        "page": 2,
+        "limit": 20,
+        "total": 156,        // total de resultados
+        "totalPages": 8,     // total de páginas
+        "hasNextPage": true,
+        "hasPrevPage": true
+      }
+    }
+  }
+}
+```
+
+---
+
+## FACETS - Filtros Dinâmicos
+
+### **O que são Facets?**
+
+Facets retornam **valores possíveis** para campos + **contagens**, permitindo criar filtros dinâmicos tipo:
+
+```
+□ Apartamento (450)
+□ Casa (280)
+□ Terreno (89)
+```
+
+### **Facets Operators - Quando usar cada um**
+
+#### **1. `operator: 'or'` - Checkbox (múltipla seleção)**
+
+**Use quando:** Usuário pode selecionar múltiplas opções **do mesmo campo**
+
+**Comportamento:** Remove filtro do campo para mostrar **todas opções disponíveis**
+
+```json
+// Request - usuário JÁ filtrou tipo=Apartamento
+{
+  "filters": {
+    "tipo": "Apartamento"  // ← filtro aplicado
+  },
+  "facets": {
+    "fields": [
+      {
+        "type": "terms",
+        "field": "tipo",
+        "operator": "or"  // ← Remove filtro de 'tipo' só para facet
+      }
+    ]
+  }
+}
+
+// Response - mostra TODAS opções (não só Apartamento)
+{
+  "facets": {
+    "data": {
+      "tipo": [
+        { "value": "Apartamento", "count": 450 },  // ← filtrado
+        { "value": "Casa", "count": 280 },          // ← também aparece
+        { "value": "Terreno", "count": 89 }         // ← também aparece
+      ]
+    }
+  }
+}
+```
+
+**UI típica:**
+```
+Tipo de Imóvel:
+☑ Apartamento (450)  ← selecionado
+□ Casa (280)         ← pode selecionar também
+□ Terreno (89)       ← pode selecionar também
+```
+
+#### **2. `operator: 'and'` - Intersecção (arrays)**
+
+**Use quando:** Valores são arrays e você quer mostrar **intersecções**
+
+**Comportamento:** Mantém filtro, mostra quais outros valores coexistem
+
+```json
+// Request - usuário filtrou características=["piscina"]
+{
+  "filters": {
+    "caracteristicas": ["piscina"]  // ← filtro aplicado
+  },
+  "facets": {
+    "fields": [
+      {
+        "type": "terms",
+        "field": "caracteristicas",
+        "operator": "and"  // ← Mantém filtro, mostra intersecções
+      }
+    ]
+  }
+}
+
+// Response - mostra características que TÊM piscina
+{
+  "facets": {
+    "data": {
+      "caracteristicas": [
+        { "value": "piscina", "count": 120 },        // ← filtrado
+        { "value": "churrasqueira", "count": 80 },   // ← 80 imóveis têm AMBOS
+        { "value": "academia", "count": 45 }         // ← 45 imóveis têm AMBOS
+      ]
+    }
+  }
+}
+```
+
+**UI típica:**
+```
+Imóveis com piscina também têm:
+☑ Piscina (120)
+□ Churrasqueira (80)  ← 80 imóveis têm piscina + churrasqueira
+□ Academia (45)       ← 45 imóveis têm piscina + academia
+```
+
+#### **3. `operator: 'equals'` - Filtro único**
+
+**Use quando:** Usuário pode selecionar **apenas 1 opção** (radio button)
+
+**Comportamento:** Mantém filtro completo, mostra **só o selecionado**
+
+```json
+// Request
+{
+  "filters": {
+    "tipo": "Apartamento"
+  },
+  "facets": {
+    "fields": [
+      {
+        "type": "terms",
+        "field": "tipo",
+        "operator": "equals"  // ← Mantém filtro
+      }
+    ]
+  }
+}
+
+// Response - mostra SÓ o filtrado
+{
+  "facets": {
+    "data": {
+      "tipo": [
+        { "value": "Apartamento", "count": 450 }  // ← só este
+      ]
+    }
+  }
+}
+```
+
+### **Range Facets - Faixas Numéricas**
+
+#### **Buckets Automáticos**
+```json
+{
+  "facets": {
+    "fields": [
+      {
+        "type": "range",
+        "field": "valor_venda",
+        "bucketCount": 4  // gera 4 faixas automaticamente
+      }
+    ]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "facets": {
+    "data": {
+      "valor_venda": [
+        { "from": 0, "to": 300000, "count": 150 },
+        { "from": 300000, "to": 600000, "count": 280 },
+        { "from": 600000, "to": 1000000, "count": 100 },
+        { "from": 1000000, "to": 5000000, "count": 39 }
+      ]
+    }
+  }
+}
+```
+
+#### **Buckets Customizados (com labels)**
+```json
+{
+  "facets": {
+    "fields": [
+      {
+        "type": "range",
+        "field": "valor_venda",
+        "buckets": [
+          { "from": 0, "to": 300000, "label": "Econômico" },
+          { "from": 300000, "to": 700000, "label": "Médio" },
+          { "from": 700000, "to": 1500000, "label": "Alto" },
+          { "from": 1500000, "to": 999999999, "label": "Premium" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "facets": {
+    "data": {
+      "valor_venda": [
+        { "from": 0, "to": 300000, "label": "Econômico", "count": 150 },
+        { "from": 300000, "to": 700000, "label": "Médio", "count": 280 },
+        { "from": 700000, "to": 1500000, "label": "Alto", "count": 100 },
+        { "from": 1500000, "to": 999999999, "label": "Premium", "count": 39 }
+      ]
+    }
+  }
+}
+```
+
+### **Range Facets - Comportamento Especial**
+
+**Range facets SEMPRE removem o filtro do campo** para mostrar todos os buckets disponíveis.
+
+```json
+// Request - usuário já filtrou valor_venda
+{
+  "filters": {
+    "valor_venda": { "gte": 300000, "lte": 700000 }  // ← filtro aplicado
+  },
+  "facets": {
+    "fields": [
+      {
+        "type": "range",
+        "field": "valor_venda",
+        "bucketCount": 4
+      }
+    ]
+  }
+}
+
+// Response - mostra TODOS os buckets (não só 300k-700k)
+{
+  "facets": {
+    "data": {
+      "valor_venda": [
+        { "from": 0, "to": 300000, "count": 150 },          // ← aparece
+        { "from": 300000, "to": 600000, "count": 280 },     // ← filtrado
+        { "from": 600000, "to": 1000000, "count": 100 },    // ← aparece
+        { "from": 1000000, "to": 5000000, "count": 39 }     // ← aparece
+      ]
+    }
+  }
+}
+```
+
+**Por quê?** Para permitir que usuário veja outras faixas e mude a seleção.
+
+---
+
+## Casos de Uso Completos
+
+### **1. Scroll Infinito + Facets**
+```json
+POST /api/property/search
+{
+  "filters": {
+    "tipo": "Apartamento"
+  },
+  "list": {
+    "limit": 20,
+    "cursor": 120  // omitir na primeira vez
+  },
+  "facets": {
+    "fields": [
+      { "type": "terms", "field": "dormitorios" },
+      { "type": "range", "field": "valor_venda", "bucketCount": 4 }
+    ]
+  }
+}
+```
+
+### **2. Paginação + Total + Mapa**
+```json
+POST /api/property/search
+{
+  "filters": {
+    "operacao": { "or": ["venda", "locacao"] },
+    "endereco_cidade": "Torres"
+  },
+  "list": {
+    "page": 1,
+    "limit": 20,
+    "select": {
+      "reference": true,
+      "title": true,
+      "valor_venda": true
+    }
+  },
+  "map": {
+    "select": {
+      "reference": true,
+      "lat": true,
+      "lng": true
+    },
+    "limit": 100
+  },
+  "meta": {}
+}
+```
+
+### **3. Full Text Search + Filtros Geo**
+```json
+POST /api/property/search
+{
+  "fts": {
+    "value": "apartamento centro piscina",
+    "operator": "websearch"
+  },
+  "geom": {
+    "operator": "within",
+    "value": {
+      "type": "bbox",
+      "bounds": {
+        "north": -29.3,
+        "south": -29.4,
+        "east": -49.65,
+        "west": -49.8
+      }
+    }
+  },
+  "list": {
+    "limit": 20
+  }
+}
+```
+
+### **4. Apenas Contagem (super rápido)**
+```json
+POST /api/property/search
+{
+  "filters": {
+    "tipo": "Apartamento",
+    "dormitorios": { "gte": 2 }
+  },
+  "meta": {}
+}
+
+// Response em ~15ms
+{
+  "results": {
+    "meta": { "total": 691 }
+  },
+  "metadata": {
+    "executionTime": 15
+  }
+}
+```
+
+### **5. Batch Search (múltiplas queries paralelas)**
+```json
+POST /api/property/batch-search
+{
+  "queries": [
+    {
+      "key": "apt-2q",
+      "filters": { "tipo": "Apartamento", "dormitorios": 2 },
+      "meta": {}
+    },
+    {
+      "key": "apt-3q",
+      "filters": { "tipo": "Apartamento", "dormitorios": 3 },
+      "meta": {}
+    },
+    {
+      "key": "casas",
+      "filters": { "tipo": "Casa" },
+      "list": { "limit": 5 }
+    }
+  ]
+}
+
+// Response com resultados separados por key
+{
+  "results": {
+    "apt-2q": {
+      "results": { "meta": { "total": 321 } },
+      "metadata": { "executionTime": 30 }
+    },
+    "apt-3q": {
+      "results": { "meta": { "total": 370 } },
+      "metadata": { "executionTime": 28 }
+    },
+    "casas": {
+      "results": { "list": {...}, "meta": {...} },
+      "metadata": { "executionTime": 45 }
+    }
+  }
+}
+```
+
+---
+
+## TypeScript Schemas
+
+### **SearchRequest**
+```typescript
+interface SearchRequest {
+  // Filtros
+  filters?: Record<string, FilterValue>;
+
+  // Full Text Search
+  fts?: {
+    value: string;
+    operator?: 'websearch' | 'plainto' | 'phrase' | 'boolean';
+  };
+
+  // Busca geográfica
+  geom?: {
+    operator: 'within' | 'intersects' | 'near';
+    value: {
+      type: 'bbox' | 'circle' | 'polygon';
+      bounds?: { north: number; south: number; east: number; west: number; };
+      center?: { lat: number; lng: number; };
+      radius?: number;
+      coordinates?: number[][];
+    };
+  };
+
+  // Serviços (escolha quais quer)
+  list?: {
+    // Offset-based
+    page?: number;
+    limit?: number;
+
+    // Cursor-based (mutuamente exclusivo com page)
+    cursor?: string | number;
+
+    // Comum
+    select?: Record<string, any>;
+    include?: Record<string, any>;
+    sort?: Record<string, 'asc' | 'desc'>;
+  };
+
+  map?: {
+    select?: Record<string, any>;
+    limit?: number;
+    bounds?: { north: number; south: number; east: number; west: number; };
+  };
+
+  meta?: {};
+
+  facets?: {
+    includeCount?: boolean;
+    fields: Array<{
+      type: 'terms' | 'range';
+      field: string;
+      operator?: 'or' | 'and' | 'equals';
+      buckets?: number[] | Array<{ from: number; to: number; label: string; }>;
+      bucketCount?: number;
+    }>;
+  };
+}
+```
+
+### **SearchResponse**
+```typescript
+interface SearchResponse {
+  results: {
+    list?: {
+      data: any[];
+      meta: {
+        limit: number;
+        hasNextPage: boolean;
+
+        // Offset-based
+        page?: number;
+        total?: number;
+        totalPages?: number;
+        hasPrevPage?: boolean;
+
+        // Cursor-based
+        nextCursor?: string | number;
+      };
+    };
+
+    map?: {
+      data: any[];
+      meta: {
+        totalWithCoordinates: number;
+      };
+    };
+
+    meta?: {
+      total: number;
+    };
+
+    facets?: {
+      data: Record<string, Array<{
+        // Terms facet
+        value?: any;
+        label?: string;
+        count?: number;
+
+        // Range facet
+        from?: number;
+        to?: number;
+      }>>;
+    };
+  };
+
+  metadata: {
+    executionTime: number;
+  };
+}
+```
+
+### **FilterValue**
+```typescript
+type FilterValue =
+  | string                          // Valor simples
+  | number
+  | boolean
+  | { or: any[] }                   // OR lógico
+  | { and: any[] }                  // AND lógico
+  | { gte: number }                 // Maior ou igual
+  | { lte: number }                 // Menor ou igual
+  | { gt: number }                  // Maior que
+  | { lt: number }                  // Menor que
+  | { between: [number, number] }   // Entre valores
+```
+
+---
+
+## Campos Disponíveis (Property)
+
+### **Principais campos para filtros/select**
+```typescript
+{
+  // Identificação
+  reference: string;
+  title: string;
+  description: string;
+
+  // Comercial
+  operacao: string[];              // ["venda", "locacao", "temporada"]
+  tipo: string;                    // "Apartamento", "Casa", etc.
+  subtipo: string;
+  valor_venda: number;
+  valor_locacao: number;
+  valor_diaria: number;
+
+  // Estrutura
+  area_total: number;
+  dormitorios: number;
+  suites: number;
+  banheiros: number;
+  vagas_garagem: number;
+
+  // Localização
+  endereco_cidade: string;
+  endereco_bairro: string;
+  lat: number;
+  lng: number;
+
+  // Características
+  caracteristicas: string[];
+  mobiliado: boolean;
+
+  // Sistema
+  created_at: string;
+  updated_at: string;
+}
+```
+
+---
+
+## Reference Rápida
+
+### **Operadores de Filtro**
+| Operador | Exemplo |
+|----------|---------|
+| Simples | `"tipo": "Apartamento"` |
+| OR | `"operacao": { "or": ["venda", "locacao"] }` |
+| AND | `"caracteristicas": { "and": ["piscina", "churrasqueira"] }` |
+| GTE | `"dormitorios": { "gte": 2 }` |
+| LTE | `"valor_venda": { "lte": 500000 }` |
+| BETWEEN | `"valor_venda": { "between": [300000, 800000] }` |
+
+### **Endpoints Disponíveis**
+```
+POST /api/property/search        # Busca multi-parte
+POST /api/property/batch-search  # Múltiplas buscas paralelas
+```
+
+### **Teste Rápido (curl)**
+```bash
+curl -X POST http://localhost:5000/api/property/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filters": { "tipo": "Apartamento" },
+    "list": { "limit": 5 },
+    "meta": {}
+  }'
+```
+
+---
+
+## Checklist Final
+
+Antes de fazer request, verifique:
+
+**Paginação:**
+- [ ] Decidiu cursor vs offset?
+- [ ] Cursor: NÃO enviar `page`
+- [ ] Offset: SEMPRE enviar `page`
+- [ ] Cursor: resetar ao mudar filtros
+
+**Facets:**
+- [ ] Checkbox múltipla? → `operator: 'or'`
+- [ ] Intersecção (arrays)? → `operator: 'and'`
+- [ ] Radio button (1 opção)? → `operator: 'equals'`
+- [ ] Range: vai mostrar TODOS os buckets
+
+**Geral:**
+- [ ] Content-Type: `application/json`
+- [ ] Campos válidos da entidade
+- [ ] Operadores corretos (`or`, `and`, `gte`, `lte`)
+
+---
+
+## RELATIONS - Campos Virtualizados
+
+### **O que são Relations?**
+
+Relations são campos que representam **relacionamentos entre entidades** definidos no Entity Schema. Por exemplo:
+- Property → Broker (imóvel pertence a um corretor)
+- Broker → Properties (corretor tem vários imóveis)
+
+### **Definindo Relations no Entity Schema**
+
+```typescript
+// apps/api/src/modules/property/schemas/entity-schema.ts
+{
+  key: "broker",
+  type: "Relation",
+  categories: ["relations"],
+  relation: {
+    model: "Broker",           // Nome do modelo Prisma
+    field: "key",              // Campo no modelo relacionado
+    labelField: "name",        // Campo para exibição
+    displayTemplate: "{{name}}",
+    foreignKey: "corretor_key" // FK nesta entidade
+  },
+  ui: { label: "Corretor" },
+  audit: { origin: "local-relation" }
+}
+
+// apps/api/src/modules/broker/schemas/entity-schema.ts
+{
+  key: "properties",
+  type: "Relation",
+  categories: ["relations"],
+  relation: {
+    model: "Property",
+    field: "corretor_key",     // Campo no Property que referencia broker
+    labelField: "title",
+    displayTemplate: "{{title}}"
+  },
+  ui: { label: "Imóveis do Corretor" },
+  audit: { origin: "local-relation" }
+}
+```
+
+### **resolveVirtualFilters - Filtros Virtuais**
+
+O sistema suporta filtros em campos virtuais (Relations) através do `resolveVirtualFilters`.
+
+**Exemplo de uso:**
+```json
+POST /api/property/search
+{
+  "filters": {
+    "broker": "joao-silva"  // Filtro virtual pelo slug do corretor
+  }
+}
+```
+
+**Como funciona internamente:**
+1. Search Engine detecta `broker` como campo Relation
+2. `resolveVirtualFilters` transforma em query real
+3. Busca broker pelo slug/key
+4. Converte para filtro: `{ corretor_key: "key-do-broker" }`
+
+### **Facets em Relations**
+
+Relations também suportam facets para criar filtros dinâmicos:
+
+```json
+{
+  "facets": {
+    "fields": [
+      {
+        "type": "terms",
+        "field": "broker",
+        "operator": "or"
+      }
+    ]
+  }
+}
+
+// Response
+{
+  "facets": {
+    "data": {
+      "broker": [
+        { "value": "joao-silva", "label": "João Silva", "count": 45 },
+        { "value": "maria-santos", "label": "Maria Santos", "count": 32 }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Arquivos de Referência
+
+### **Código Fonte**
+- **Controller**: `/apps/api/src/modules/property/controllers/search.controller.ts`
+- **Service**: `/apps/api/src/modules/property/services/search.service.ts`
+- **Types**: `/apps/api/src/lib/advancedSearch/types.ts`
+- **Cursor Pagination**: `/apps/api/src/lib/advancedSearch/executeList.ts` (linha 46)
+
+### **Biblioteca Genérica**
+- **Advanced Search**: `/apps/api/src/lib/advancedSearch/index.ts`
+- **Facets System**: `/apps/api/src/lib/advancedSearch/facets/index.ts`
+- **Relations Enricher**: `/apps/api/src/lib/advancedSearch/facets/enrichers/relation.ts`
+
+### **Entity Schemas**
+- **Property**: `/apps/api/src/modules/property/schemas/entity-schema.ts`
+- **Broker**: `/apps/api/src/modules/broker/schemas/entity-schema.ts`