@horizon-framework/website-dev-docs 2.3.0

package/knowledge/API_PROPERTY.md

@@ -0,0 +1,566 @@
+# API Property -- Stack, Arquitetura e Endpoints
+
+> **Status:** **PRODUÇÃO PRONTA**  
+> **Versão:** 3.0.0 (Property + Broker implementados)  
+> **Data:** 23/08/2025
+
+## **Visão Geral**
+
+API Next.js moderna para gestão e busca de propriedades imobiliárias com arquitetura avançada, busca full-text, geolocalização PostGIS e sistema de migração completo da nomenclatura IMOVEL→PROPERTY e CORRETOR→BROKER.
+
+### **Stack Tecnológico**
+- **Next.js 14** (App Router)
+- **Prisma 5.22** (ORM + Client)  
+- **PostgreSQL** (Neon Database com PostGIS)
+- **TypeScript** (strict mode)
+- **Zod 3.24** (validação + inferência de tipos)
+- **Vitest** (framework de testes)
+
+### **Principais Recursos**
+- **SSOT v2.0** - Single Source of Truth com 90+ campos estruturados
+- **Advanced Search Library** - Biblioteca isolada e reutilizável (8 módulos)
+- **Type-safety completo** - Zod + TypeScript em toda stack
+- **Prisma DMMF Introspection** - Detecção automática de tipos
+- **API RESTful robusta** - Validação completa com Zod
+- **PostGIS Integration** - Busca geoespacial avançada
+- **Full-text Search** - PostgreSQL tsvector com português
+- **Migração completa** - Sistema legacy totalmente modernizado
+
+---
+
+## **Estrutura do Projeto**
+
+```
+/apps/api/
+├── prisma/                           # Database & Schema
+│   ├── schema.prisma                    # Schema completo (Property + Broker)
+│   └── db-setup.sql                     # PostGIS extensions
+├── src/
+│   ├── app/api/                      # Next.js Routes (pontes secas)
+│   │   └── property/                    # Endpoints do módulo Property
+│   │       ├── find/route.ts            # POST - busca por criteria
+│   │       ├── search/route.ts          # POST - busca multipart
+│   │       ├── sync/route.ts            # GET/PUT - sincronização
+│   │       └── schemas/                 # GET - schemas SSOT
+│   ├── core/
+│   │   └── prisma.ts                    # Singleton Prisma Client
+│   └── modules/property/             # Módulo principal
+│       ├── config/
+│       │   ├── entity-schema.ts         # SSOT v2.0 (~1000 linhas)
+│       │   ├── entity-schema.zod.ts     # Schemas Zod gerados
+│       │   └── database/
+│       │       ├── fragment.prisma      # Fragment para geração
+│       │       └── fragment.sql         # SQL índices especiais
+│       ├── controllers/              # Controllers Next.js
+│       │   ├── search.controller.ts     # Busca multipart
+│       │   ├── find.controller.ts       # Busca por criteria
+│       │   ├── sync.controller.ts       # Sincronização batch
+│       │   └── schemas.controller.ts    # Schemas SSOT
+│       ├── lib/advancedSearch/       # BIBLIOTECA ISOLADA
+│       │   ├── index.ts                 # API principal
+│       │   ├── types.ts                 # Definições tipos
+│       │   ├── extractIds.ts            # Extração IDs fulltext/geo
+│       │   ├── executeList.ts           # Busca paginada
+│       │   ├── executeMap.ts            # Busca para mapas
+│       │   ├── executeTotal.ts          # Contagem total
+│       │   ├── executeFacets.ts         # Agregações/facets
+│       │   └── helpers.ts               # DMMF Introspection
+│       ├── services/                 # Services de negócio
+│       │   ├── search.service.ts        # Service busca
+│       │   ├── find.service.ts          # Service find
+│       │   └── sync.service.ts          # Service sincronização
+│       └── mappers/                  # Transformadores dados
+│           └── enrichPropertyData/      # Enriquecimento dados
+├── __tests__/                        # Suíte completa de testes
+├── __dev__/                          # Scripts desenvolvimento
+│   ├── scripts/                         # Scripts utilitários
+│   └── data/                            # Dados Jetimob (11 páginas)
+└── docs/                             # Documentação completa
+```
+
+---
+
+## **Database Schema**
+
+### **Model Property (~90 campos)**
+```prisma
+model Property {
+  // BASE SYSTEM
+  id         Int      @id @default(autoincrement())
+  created_at DateTime @default(now())
+  
+  // SPECIAL GENERATED COLUMNS
+  search_tsvector Unsupported("tsvector")? // Full-text search
+  location        Unsupported("geometry")? // PostGIS Point
+  
+  // CORE IDENTIFICATION
+  reference   String   @unique              // Código único
+  title       String                       // Título
+  description String                       // Descrição
+  
+  // COMMERCIAL
+  operacao         String[]                 // ["venda", "locacao", "temporada"]
+  valor_venda      Float?                   // Preço venda
+  valor_locacao    Float?                   // Preço aluguel
+  valor_diaria     Float?                   // Preço diária
+  
+  // STRUCTURE
+  area_total     Float?                     // Área m²
+  dormitorios    Int?                       // Quartos
+  banheiros      Int?                       // Banheiros
+  vagas_garagem  Int?                       // Vagas
+  tipo           String?                    // casa, apartamento
+  subtipo        String?                    // cobertura, duplex
+  
+  // LOCATION
+  endereco_cidade      String?              // Cidade
+  endereco_bairro      String?              // Bairro
+  endereco_logradouro  String?              // Rua
+  lat                  Float?               // Latitude
+  lng                  Float?               // Longitude
+  
+  // CHARACTERISTICS
+  caracteristicas String[]                  // ["piscina", "churrasqueira"]
+  tags           String[]                   // Tags livres
+  
+  // BROKER/AGENT
+  corretor_nome String?                     // Nome broker
+  
+  // CONDOMINIUM
+  condominio_nome        String?            // Nome condomínio
+  condominio_comodidades String[]          // ["academia", "sauna"]
+  
+  // JETIMOB ESPECÍFICOS (50+ campos adicionais)
+  // ... muitos outros campos do provider
+}
+```
+
+### **Colunas Especiais Geradas**
+```sql
+-- Full-text search (25+ campos indexados)
+ALTER TABLE "Property"
+  ADD COLUMN search_tsvector tsvector GENERATED ALWAYS AS (
+    immutable_to_tsvector(
+      coalesce("title",'') || ' ' || 
+      coalesce("description",'') || ' ' ||
+      coalesce("endereco_cidade",'') || ' ' ||
+      coalesce("endereco_bairro",'') || ' ' ||
+      coalesce(immutable_array_to_string("caracteristicas", ' '),'')
+      -- ... 25+ campos searchables
+    )
+  ) STORED;
+
+-- Geospatial Point (PostGIS)
+ALTER TABLE "Property"
+  ADD COLUMN location geometry(Point, 4326) GENERATED ALWAYS AS (
+    ST_SetSRID(ST_MakePoint(lng::double precision, lat::double precision), 4326)
+  ) STORED;
+```
+
+---
+
+## **SSOT v2.0 - Single Source of Truth**
+
+### **Arquivo:** `src/modules/property/config/entity-schema.ts`
+
+**Sistema hierárquico** de metadados que define TODA a estrutura da entidade Property:
+
+```typescript
+interface FieldSchema {
+  key: string;                    // Nome campo
+  type: string;                   // Tipo TypeScript
+  categories: string[];           // Agrupamento
+  validation?: Record<string, any>; // Regras Zod
+  ui: {
+    label: string;                // Label UI
+    description: string;          // Descrição
+    searchable?: boolean;         // Se é searchable
+    filterable?: boolean;         // Se é filterable
+    // ... mais configs UI
+  };
+  audit: {
+    origin: string;              // Origem do campo
+  };
+  enum?: Record<string, string>; // Valores enum
+  rules?: {                     // Regras condicionais
+    conditions?: string[];
+    parent?: string;
+  };
+}
+```
+
+### **Benefícios SSOT:**
+- **Zero hardcoding** - Tudo baseado no schema
+- **Geração automática** - Zod schemas + TypeScript types
+- **Documentação viva** - Schema é a documentação
+- **Validação consistente** - Uma fonte, múltiplos usos
+- **90+ campos estruturados** - Jetimob + Horizon + Custom
+
+---
+
+## **Advanced Search Library**
+
+### **8 Módulos Isolados**
+
+| Módulo | Responsabilidade | Funcionalidade |
+|--------|------------------|----------------|
+| **`index.ts`** | API principal | Orquestra busca multipart |
+| **`types.ts`** | Tipos TypeScript | SearchRequest, Response, Config |
+| **`extractIds.ts`** | Extração IDs | Full-text + geolocalização |
+| **`executeList.ts`** | Lista paginada | SELECT + include + pagination |
+| **`executeMap.ts`** | Dados mapa | Lat/lng otimizado |
+| **`executeTotal.ts`** | Contagem | COUNT queries |
+| **`executeFacets.ts`** | Agregações | GROUP BY dinâmicos |
+| **`helpers.ts`** | DMMF Introspection | Detecção automática tipos |
+
+### **API Super Simples**
+```typescript
+// 95% automático, 5% configurado
+const config = { 
+  modelName: 'Property',
+  searchColumn: 'search_tsvector',  // opcional
+  locationColumn: 'location'        // opcional
+};
+
+const result = await advancedSearch(prisma, request, config);
+```
+
+### **Funcionalidades Avançadas**
+
+#### **1. Prisma DMMF Introspection**
+```typescript
+// Detecta automaticamente se campo é array ou simples
+export function getFieldType(prisma, modelName, fieldName): 'array' | 'simple' {
+  const field = prisma.dmmf.datamodel.models
+    .find(m => m.name === modelName)
+    .fields.find(f => f.name === fieldName);
+  
+  return field.isList ? 'array' : 'simple';
+}
+
+// Usa operador correto automaticamente
+if (Array.isArray(value)) {
+  const fieldType = getFieldType(prisma, modelName, key);
+  where[key] = fieldType === 'array' 
+    ? { hasSome: value }  // String[] field
+    : { in: value };      // String field
+}
+```
+
+#### **2. Busca Multipart**
+```typescript
+// Uma requisição → múltiplas respostas
+const request = {
+  filters: { endereco_cidade: "Florianópolis" },
+  search: { value: "casa piscina" },
+  location: { 
+    operation: "within",
+    geometry: { type: "bbox", bounds: {...} }
+  },
+  list: { page: 1, limit: 10 },      // Lista paginada
+  map: { fields: ["lat", "lng"] },   // Dados mapa
+  meta: { total: true },             // Contagem
+  facets: { fields: ["tipo"] }       // Agregações
+};
+```
+
+---
+
+## **API Endpoints**
+
+### **Pattern "Ponte Seca"**
+Routes em `/app/api/` apenas exportam controllers:
+
+```typescript
+// /app/api/property/search/route.ts
+export { POST } from '@/modules/property/controllers/search.controller';
+```
+
+### **Endpoints Disponíveis**
+
+| Método | Endpoint | Função | Controller |
+|--------|----------|---------|-----------|
+| `POST` | `/api/property/search` | Busca multipart | search.controller.ts |
+| `POST` | `/api/property/find` | Busca criteria | find.controller.ts |
+| `GET` | `/api/property/sync` | Listing integração | sync.controller.ts |
+| `PUT` | `/api/property/sync` | Upsert batch | sync.controller.ts |
+| `GET` | `/api/property/schemas/entity` | Schema SSOT | schemas.controller.ts |
+
+### **Exemplo Busca Multipart**
+```bash
+curl -X POST http://localhost:5000/api/property/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filters": {
+      "endereco_cidade": "Florianópolis",
+      "operacao": ["venda"],
+      "dormitorios": [2, 3, 4]
+    },
+    "search": {
+      "value": "apartamento com piscina"
+    },
+    "location": {
+      "operation": "within",
+      "geometry": {
+        "type": "bbox",
+        "bounds": {
+          "north": -27.5,
+          "south": -27.7,
+          "east": -48.4,
+          "west": -48.6
+        }
+      }
+    },
+    "list": {
+      "page": 1,
+      "limit": 20,
+      "select": {
+        "id": true,
+        "title": true,
+        "valor_venda": true,
+        "area_total": true,
+        "dormitorios": true
+      }
+    },
+    "map": {
+      "select": {
+        "id": true,
+        "lat": true,
+        "lng": true,
+        "valor_venda": true
+      }
+    },
+    "meta": { "total": true },
+    "facets": {
+      "fields": [
+        { "type": "terms", "field": "tipo" },
+        { "type": "terms", "field": "endereco_bairro" },
+        { "type": "range", "field": "valor_venda", "buckets": [100000, 300000, 500000] }
+      ]
+    }
+  }'
+```
+
+**Response:**
+```json
+{
+  "results": {
+    "list": {
+      "data": [
+        {
+          "id": 1,
+          "title": "Apartamento 3 dormitórios com piscina",
+          "valor_venda": 450000,
+          "area_total": 120.50,
+          "dormitorios": 3
+        }
+      ],
+      "meta": {
+        "page": 1,
+        "limit": 20,
+        "total": 150,
+        "totalPages": 8,
+        "hasNextPage": true
+      }
+    },
+    "map": {
+      "data": [
+        {
+          "id": 1,
+          "lat": -27.5969,
+          "lng": -48.5495,
+          "valor_venda": 450000
+        }
+      ],
+      "meta": { "totalWithCoordinates": 127 }
+    },
+    "meta": { "total": 150 },
+    "facets": {
+      "data": {
+        "tipo": [
+          { "value": "apartamento", "count": 89 },
+          { "value": "casa", "count": 61 }
+        ],
+        "endereco_bairro": [
+          { "value": "Centro", "count": 45 },
+          { "value": "Trindade", "count": 32 }
+        ],
+        "valor_venda": [
+          { "range": "0-100000", "count": 15 },
+          { "range": "100000-300000", "count": 67 },
+          { "range": "300000-500000", "count": 42 },
+          { "range": "500000+", "count": 26 }
+        ]
+      }
+    }
+  },
+  "metadata": {
+    "executionTime": 89
+  }
+}
+```
+
+---
+
+## **Testes Completos**
+
+### **Suíte de Testes:** `__tests__/`
+
+| Teste | Status | Descrição |
+|-------|--------|-----------|
+| `final-integration.test.ts` | | Teste integração completa API |
+| `new-api-advanced-search.test.ts` | | API isolada biblioteca |
+| `debug-advanced-search.test.ts` | | Debug específicos |
+| `prisma-introspection.test.ts` | | DMMF introspection |
+
+### **Executar Testes**
+```bash
+# Todos os testes
+pnpm test
+
+# Teste específico
+pnpm vitest run __tests__/final-integration.test.ts
+
+# Watch mode
+pnpm test:watch
+```
+
+---
+
+## **Comandos Principais**
+
+### **Desenvolvimento**
+```bash
+# Instalar dependências
+pnpm install
+
+# Desenvolvimento (porta 5000)
+pnpm dev
+
+# Build produção
+pnpm build
+```
+
+### **Database**
+```bash
+# Gerar Prisma Client
+pnpm prisma:generate
+
+# Push schema
+pnpm prisma:push
+
+# Executar fragment SQL
+PGPASSWORD=$POSTGRES_PASSWORD psql $DATABASE_URL -f src/modules/property/config/database/fragment.sql
+```
+
+### **Scripts Desenvolvimento**
+```bash
+# Upload dados Jetimob (chunks)
+pnpm tsx __dev__/scripts/sync-properties-chunked.ts
+
+# Geração Zod schemas
+pnpm tsx __dev__/scripts/generate-zod.ts
+```
+
+---
+
+## **Migração Concluída**
+
+### **FASE COMPLETA: IMOVEL → PROPERTY + CORRETOR → BROKER**
+
+A aplicação passou por **migração completa** de nomenclatura e arquitetura:
+
+- **Renomeação massiva** - 50+ arquivos atualizados
+- **Database migration** - Tabelas Property + Broker
+- **API endpoints** - `/api/property/*` funcionais
+- **Type-safety** - Zero breaking changes
+- **Backward compatibility** - Sistemas legados funcionando
+- **Tests passing** - Suíte completa validada
+
+### **Scripts de Migração**
+```bash
+# Aplicados e concluídos:
+./__dev__/scripts/rename-imovel-to-property.sh    
+./__dev__/scripts/rename-corretor-to-broker.sh    
+```
+
+---
+
+## **Performance & Otimizações**
+
+### **Índices Database**
+- **B-Tree:** reference, created_at, tipo, endereco_cidade
+- **GIN:** search_tsvector (full-text)
+- **GIST:** location (geospatial)
+- **Composite:** [lat, lng], [status], [valor_venda]
+
+### **Queries Otimizadas**
+- **Select específico** por tipo resposta
+- **Execução paralela** de múltiplas queries
+- **Prepared statements** via Prisma
+- **Paginação eficiente** com limit/offset
+
+### **Caching**
+- **Prisma Client** singleton
+- **ETag** para schemas estáticos
+- **Database connection pooling**
+
+---
+
+## **Dados Atuais**
+
+### **Status Database**
+- **1.076 propriedades** Jetimob importadas
+- **search_tsvector** populado em todas
+- **location geometry** populado com lat/lng válidos
+- **Índices** todos criados e funcionais
+
+### **Coverage Campos**
+- **90+ campos** mapeados no SSOT
+- **25+ campos** indexados para busca full-text
+- **Geolocalização** em 98% das propriedades
+- **Arrays** (caracteristicas, operacao, tags) funcionais
+
+---
+
+## **Próximos Passos**
+
+### **Funcionalidades Futuras**
+- [ ] **Cache avançado** (Redis)
+- [ ] **API versioning** (v1/v2)
+- [ ] **GraphQL endpoint** (opcional)
+- [ ] **Webhooks** para integração
+- [ ] **Rate limiting**
+- [ ] **Authentication/Authorization**
+
+### **Melhorias Técnicas**
+- [ ] **Monitoring** (APM)
+- [ ] **Logging estruturado**
+- [ ] **Health checks** avançados
+- [ ] **Docker deployment**
+- [ ] **CI/CD pipeline**
+
+---
+
+## **Equipe & Contato**
+
+**Desenvolvido por:** Jefferson Rosa  
+**Versão:** 3.0.0  
+**Status:** **PRODUÇÃO PRONTA**  
+**Última Atualização:** 23/08/2025
+
+---
+
+## **Conclusão**
+
+Este projeto representa uma **evolução significativa** na arquitetura de APIs imobiliárias:
+
+- **Arquitetura moderna** e escalável
+- **Type safety** em toda stack  
+- **Biblioteca reutilizável** isolada
+- **Performance otimizada** com PostGIS
+- **API robusta** com validação completa
+- **Migração completa** do sistema legacy
+- **Testes abrangentes** garantindo qualidade
+
+A aplicação está **pronta para produção** e serve como **base sólida** para futuras expansões no ecossistema Nova Torres.