@horizon-domains/property-model/README.md

Modelo de propriedades imobiliárias v3 - Sistema de atributos dinâmicos

# @horizon-domains/property-model

🏠 **Modelo padronizado de propriedades imobiliárias** com schema JSON, validação Zod, dados fake para testes e gerador de dados sintéticos.

## 📦 Instalação

```bash
pnpm add @horizon-domains/property-model
# ou
npm install @horizon-domains/property-model
```

## 🚀 Uso Básico

### 📋 Schema JSON Base

```typescript
import { HorizonPropertySchemaBase } from '@horizon-domains/property-model'

// Schema JSON com definição de 52+ campos
console.log(HorizonPropertySchemaBase.fields.length) // 52+ campos definidos
```

### ✅ Validação com Zod

```typescript
import { 
  HorizonPropertySchemaBaseZod,
  type HorizonPropertySchemaBaseType 
} from '@horizon-domains/property-model'

// Validar dados de propriedade
const propertyData = {
  reference: "PROP_001",
  titulo: "Apartamento 3 quartos",
  descricao: "Apartamento moderno no centro da cidade...",
  tipo: "Apartamento",
  dormitorios: 3,
  valor_venda: 450000
}

// Validação com Zod
const validProperty: HorizonPropertySchemaBaseType = HorizonPropertySchemaBaseZod.parse(propertyData)

// Validação safe (não lança erro)
const result = HorizonPropertySchemaBaseZod.safeParse(propertyData)
if (result.success) {
  console.log("Propriedade válida:", result.data)
} else {
  console.log("Erros de validação:", result.error.issues)
}
```

### 🎨 Dados Fake para Testes

```typescript
import { 
  FakeDataApartamentos,
  FakeDataCasasSobrados,
  FakeDataComerciais,
  FakeDataIndustriais,
  FakeDataRurais,
  FakeDataTerrenosLotes,
  FakeDataAllProperties
} from '@horizon-domains/property-model'

// Usar dados fake específicos por categoria
console.log(FakeDataApartamentos.length)     // ~15 apartamentos
console.log(FakeDataCasasSobrados.length)    // ~10 casas/sobrados
console.log(FakeDataComerciais.length)       // ~15 comerciais
console.log(FakeDataAllProperties.length)    // ~100 propriedades totais

// Exemplo de uso em testes
const primeiroApartamento = FakeDataApartamentos[0]
console.log(primeiroApartamento.tipo)        // "Apartamentos"
console.log(primeiroApartamento.subtipo)     // "Apartamento Padrão", "Cobertura", etc.
```

### 🎯 Gerador de Dados Sintéticos

```typescript
import { 
  FakeDataGenerator,
  type FakeDataConfig,
  fakeDataConfigExample 
} from '@horizon-domains/property-model'

// Usar configuração de exemplo
const generator = new FakeDataGenerator({
  totalProperties: 50,
  dataConfig: fakeDataConfigExample,
  categorizeByType: true,
  includeImages: true,
  outputDir: './fake-data-output'
})

// Gerar dados sintéticos
await generator.generate()

// Ou criar sua própria configuração
const customConfig: FakeDataConfig = {
  tipos: ["Apartamentos", "Casas/Sobrados"],
  subtipos: {
    "Apartamentos": ["Apartamento Padrão", "Cobertura"],
    "Casas/Sobrados": ["Casa", "Sobrado"]
  },
  finalidades: ["Residencial"],
  estados: ["São Paulo", "Rio de Janeiro"],
  cidades: {
    "São Paulo": ["São Paulo", "Campinas"],
    "Rio de Janeiro": ["Rio de Janeiro", "Niterói"]
  },
  // ... mais configurações
  ranges: {
    dormitorios: [1, 4],
    valor_venda: [200000, 1000000],
    area_total: [50, 200]
  }
}
```

### 🛠️ Utilitários

```typescript
import { 
  mergePropertyAttributesModel,
  sortAttributes,
  preparaAttrValueLabel 
} from '@horizon-domains/property-model'

// Utilitários para manipulação de propriedades
const mergedProperty = mergePropertyAttributesModel(baseProperty, newAttributes)
const sortedAttrs = sortAttributes(property.attributes)
const formattedLabel = preparaAttrValueLabel(value, field)
```

## 📊 Estrutura de Dados

### 🏠 PropertyV3 - Campos Principais

```typescript
interface HorizonPropertySchemaBaseType {
  // === IDENTIFICAÇÃO ===
  reference: string                    // Referência única (obrigatório)
  updated_at?: string                  // Timestamp de atualização
  titulo: string                       // Título da propriedade (obrigatório)
  descricao: string                    // Descrição detalhada (obrigatório)
  slug?: string                        // URL slug
  
  // === SEO ===
  seo_title?: string                   // Título SEO (max 60 chars)
  seo_description?: string             // Descrição SEO (max 160 chars)
  seo_keywords?: string                // Palavras-chave SEO
  
  // === CONFIGURAÇÕES ===
  moeda?: "BRL" | "USD"                // Moeda (padrão: BRL)
  unidade_area?: "m2" | "ft2"          // Unidade de área (padrão: m2)
  unidade_distancia?: "km" | "mi" | "meters"  // Unidade de distância
  
  // === MÍDIA ===
  imagens: any[]                       // Array de imagens
  videos: any[]                        // Array de vídeos
  tours_virtuais: any[]                // Tours 360°
  documentos: any[]                    // Documentos anexos
  
  // === COMERCIAL ===
  operacao?: string[]                  // Venda, aluguel, temporada
  valor_venda?: number                 // Valor de venda
  valor_aluguel?: number               // Valor do aluguel
  valor_diaria?: number                // Valor da diária
  valor_condominio?: number            // Taxa de condomínio
  valor_iptu?: number                  // Valor do IPTU
  
  // === CARACTERÍSTICAS FÍSICAS ===
  area_total?: number                  // Área total
  area_privativa?: number              // Área privativa
  area_util?: number                   // Área útil
  dormitorios?: number                 // Número de dormitórios
  suites?: number                      // Número de suítes
  banheiros?: number                   // Número de banheiros
  vagas_garagem?: number               // Vagas de garagem
  
  // === CLASSIFICAÇÃO ===
  finalidade?: string                  // Residencial, comercial, etc.
  tipo?: string                        // Apartamento, casa, terreno, etc.
  subtipo?: string                     // Studio, cobertura, etc.
  
  // === LOCALIZAÇÃO ===
  endereco_cep?: string                // CEP
  endereco_estado?: string             // Estado
  endereco_cidade?: string             // Cidade
  endereco_bairro?: string             // Bairro
  endereco_logradouro?: string         // Rua/Avenida
  endereco_numero?: string             // Número
  endereco_complemento?: string        // Complemento
  endereco_referencia?: string         // Ponto de referência
  endereco_zona?: string               // Zona da cidade
  latitude?: number                    // Coordenada GPS
  longitude?: number                   // Coordenada GPS
  
  // === CARACTERÍSTICAS ===
  mobiliado?: boolean                  // Se é mobiliado
  caracteristicas?: string[]           // Lista de características
  destaque?: boolean                   // Se é propriedade em destaque
  
  // === RELACIONAMENTOS ===
  corretor_id?: string                 // ID do corretor
  corretor_nome?: string               // Nome do corretor
  condominio_id?: string               // ID do condomínio
  condominio_nome?: string             // Nome do condomínio
  
  // === METADATA ===
  tags?: string                        // Tags da propriedade
  numero_pessoas?: number              // Capacidade de pessoas
}
```

### 🎨 FakeDataConfig - Configuração do Gerador

```typescript
interface FakeDataConfig {
  tipos: string[]                      // Tipos de imóveis
  subtipos: Record<string, string[]>   // Subtipos por tipo
  finalidades: string[]                // Finalidades
  estados: string[]                    // Estados
  cidades: Record<string, string[]>    // Cidades por estado
  bairros: Record<string, string[]>    // Bairros por cidade
  logradouros: string[]                // Nomes de ruas
  zonas: string[]                      // Zonas da cidade
  caracteristicas: string[]            // Características possíveis
  
  ranges: {
    dormitorios: number[]              // Range [min, max]
    suites: number[]
    banheiros: number[]
    vagas_garagem: number[]
    area_total: number[]
    area_privativa: number[]
    area_util: number[]
    valor_venda: number[]
    valor_aluguel: number[]
    valor_diaria: number[]
    valor_condominio: number[]
    valor_iptu: number[]
    numero_pessoas: number[]
  }
  
  images: {
    apartamento: string[]              // URLs de imagens Unsplash
    casa: string[]
    sobrado: string[]
    cobertura: string[]
    terreno: string[]
    comercial: string[]
    default: string[]
  }
  
  condominios: Record<string, string[]>
  corretores: Array<{id: string, nome: string}>
}
```

## 📂 Dados Fake Incluídos

O pacote inclui **~100 propriedades fake** pré-geradas e categorizadas:

- **FakeDataApartamentos** (~15 propriedades)
- **FakeDataCasasSobrados** (~10 propriedades)  
- **FakeDataComerciais** (~15 propriedades)
- **FakeDataIndustriais** (~24 propriedades)
- **FakeDataRurais** (~19 propriedades)
- **FakeDataTerrenosLotes** (~17 propriedades)
- **FakeDataAllProperties** (todas as ~100 propriedades)

### Características dos Dados Fake:

- ✅ **Validados com Zod** - Todos passam na validação do schema
- 🏞️ **Imagens reais** - URLs do Unsplash categorizadas por tipo
- 🎯 **Dados realistas** - Baseados em propriedades reais do mercado
- 📍 **Localização brasileira** - Estados, cidades e bairros reais
- 💰 **Valores de mercado** - Preços compatíveis com cada região/tipo

## 🛠️ Desenvolvimento

### Scripts Disponíveis

```bash
# Gerar schemas Zod a partir do JSON
pnpm generate:zod

# Gerar dados fake
pnpm dev:generate-fake

# Customizar propriedades existentes
pnpm dev:customize

# Testes
pnpm test

# Build
pnpm build

# Type check
pnpm typecheck
```

### Estrutura do Projeto

```
src/
├── schemas/
│   ├── horizon-property-schema-base.json     # 📋 Schema JSON (SSOT)
│   └── generated/
│       └── horizon-property-schema-base.zod.ts  # ✅ Schema Zod gerado
├── data/fake-properties/                     # 🎨 Dados fake exportados
│   ├── fake-apartamentos.json
│   ├── fake-casas-sobrados.json
│   └── ...
├── services/
│   └── FakeDataGenerator.ts                 # 🎯 Gerador de dados sintéticos
├── config/
│   └── fake-data-config-example.ts          # ⚙️ Config de exemplo
└── utils/                                   # 🛠️ Utilitários
```

## 🔧 Geração de Dados Personalizados

### Exemplo Completo

```typescript
import { FakeDataGenerator, type FakeDataConfig } from '@horizon-domains/property-model'

const config: FakeDataConfig = {
  tipos: ["Apartamentos", "Casas/Sobrados"],
  subtipos: {
    "Apartamentos": ["Apartamento Padrão", "Cobertura", "Studio"],
    "Casas/Sobrados": ["Casa", "Sobrado", "Casa de Condomínio"]
  },
  finalidades: ["Residencial"],
  estados: ["São Paulo"],
  cidades: {
    "São Paulo": ["São Paulo", "Santos", "Campinas"]
  },
  bairros: {
    "São Paulo": ["Vila Madalena", "Pinheiros", "Itaim Bibi"],
    "Santos": ["Gonzaga", "José Menino", "Embaré"],
    "Campinas": ["Cambuí", "Centro", "Jardim Guanabara"]
  },
  logradouros: [
    "Rua das Flores", "Avenida Paulista", "Rua Augusta"
  ],
  zonas: ["Centro", "Zona Sul", "Zona Oeste"],
  caracteristicas: [
    "Piscina", "Academia", "Churrasqueira", "Varanda",
    "Ar Condicionado", "Portaria 24h"
  ],
  ranges: {
    dormitorios: [1, 4],
    suites: [0, 2],
    banheiros: [1, 3],
    vagas_garagem: [1, 3],
    area_total: [45, 200],
    area_privativa: [40, 180],
    area_util: [35, 160],
    valor_venda: [250000, 1500000],
    valor_aluguel: [1500, 8000],
    valor_diaria: [100, 500],
    valor_condominio: [300, 1200],
    valor_iptu: [800, 5000],
    numero_pessoas: [2, 6]
  },
  images: {
    apartamento: [
      "https://images.unsplash.com/photo-1522708323590-d24dbb6b0267?w=800",
      "https://images.unsplash.com/photo-1502672260266-1c1ef2d93688?w=800"
    ],
    casa: [
      "https://images.unsplash.com/photo-1564013799919-ab600027ffc6?w=800",
      "https://images.unsplash.com/photo-1570129477492-45c003edd2be?w=800"
    ],
    // ... mais categorias
    default: [
      "https://images.unsplash.com/photo-1560518883-ce09059eeffa?w=800"
    ]
  },
  condominios: {
    "São Paulo": [
      "Residencial Park View",
      "Condomínio Jardim das Flores",
      "Edifício Solar do Itaim"
    ]
  },
  corretores: [
    { id: "COR001", nome: "Ana Silva" },
    { id: "COR002", nome: "Carlos Santos" }
  ]
}

// Gerar propriedades
const generator = new FakeDataGenerator({
  totalProperties: 30,
  dataConfig: config,
  categorizeByType: true,
  includeImages: true,
  outputDir: './meus-dados-fake',
  verbose: true
})

await generator.generate()
```

## ⚡ Performance

- **Schema JSON**: ~52 campos definidos com metadados
- **Validação Zod**: Validação rápida em runtime  
- **Dados Fake**: ~100 propriedades pré-geradas válidas
- **Gerador**: Capaz de gerar centenas de propriedades por minuto
- **Bundle Size**: Otimizado para uso em produção

## 📄 Licença

MIT © Horizon Labs

---

**🏗️ Horizon Labs** - Padronizando o mercado imobiliário digital