@horizon-modules/property-model-v3/docs/REFATORACAO_PROPERTY_MODEL_V3.md

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

# Refatoração Property Model V3 - Documentação Técnica

## 📋 Entendimento do Projeto

### **Situação Atual**
O `property-model-v3` possui:
- ✅ Modelo PropertyModel unificado em `property-type.schema.ts`
- ✅ Fake data generator básico usando imagens locais
- ✅ Custom mapper com validação Zod
- ❌ Dependência de assets locais (removida)
- ❌ Falta de profiling e dados reais de exemplo
- ❌ Estrutura de desenvolvimento incompleta

### **Estrutura do Arbo-CRM Analisada**
```
arbo-crm/
├── __dev__/
│   ├── data/
│   │   ├── downloads-do-crm/        # Dados reais baixados da API
│   │   ├── fake-data-output/        # Dados fake gerados
│   │   ├── mock-output/             # Mocks para testes
│   │   └── profiling-report.json    # Análise dos dados
│   ├── scripts/
│   │   ├── download-properties.js   # Baixa dados da API
│   │   ├── generate-fake-data.ts    # Gera dados fake
│   │   ├── generate-mocks.ts        # Gera mocks
│   │   └── profile-properties.js    # Faz profiling
│   ├── services/
│   │   ├── FakeDataGeneratorService.ts
│   │   └── MockGeneratorService.ts
│   └── tests/
│       ├── fakeDataGeneratorService.test.ts
│       └── mockGeneratorService.test.ts
└── src/
    └── data/
        ├── fake-data/    # Dados fake finais exportados
        └── mock/         # Mocks finais exportados
```

## 🎯 Objetivo da Refatoração

### **1. Migrar para Unsplash**
- ❌ Remover pasta `/src/assets` com imagens locais
- ✅ Usar URLs do Unsplash como no arbo-crm
- ✅ Gerar imagens fake usando Unsplash

### **2. Criar Estrutura de Desenvolvimento**
```
property-model-v3/
├── __dev__/
│   ├── data/
│   │   ├── arbo-downloads/          # Dados reais do Arbo convertidos
│   │   ├── fake-data-output/        # Dados fake gerados (PropertyModel)
│   │   ├── mock-output/             # Mocks para testes
│   │   └── profiling-report.json    # Análise dos dados PropertyModel
│   ├── scripts/
│   │   ├── download-from-arbo.ts    # Baixa do arbo-crm e converte
│   │   ├── generate-fake-data.ts    # Gera dados fake PropertyModel
│   │   ├── generate-mocks.ts        # Gera mocks PropertyModel
│   │   └── profile-properties.ts    # Faz profiling PropertyModel
│   ├── services/
│   │   ├── ArboDownloaderService.ts # Integra com arbo-crm
│   │   ├── FakeDataGeneratorService.ts
│   │   ├── MockGeneratorService.ts
│   │   └── ProfilerService.ts
│   └── tests/
│       ├── arboDownloaderService.test.ts
│       ├── fakeDataGeneratorService.test.ts
│       ├── mockGeneratorService.test.ts
│       └── profilerService.test.ts
└── src/
    └── data/
        ├── fake-data/    # Dados fake selecionados manualmente
        ├── examples/     # Exemplos reais convertidos do Arbo
        └── profiling/    # Dados de profiling para uso em produção
```

### **3. Fluxo de Trabalho**
1. **Download & Conversão**: Baixar dados do arbo-crm → converter para PropertyModel
2. **Profiling**: Analisar dados convertidos → gerar relatório de profiling
3. **Geração Fake**: Usar profiling para gerar dados fake realistas
4. **Geração Mocks**: Criar mocks para testes baseados no profiling
5. **Seleção Manual**: Copiar dados fake selecionados para `/src/data`
6. **Export NPM**: Dados em `/src/data` são exportados no pacote

## 🔧 Tecnologias e Dependências

### **Dependências Necessárias**
```json
{
  "dependencies": {
    "@horizon-modules/arbo-crm-integration": "^2.0.1",
    "ramda": "^0.30.0",
    "zod": "^3.25.67"
  },
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0",
    "vitest": "^1.0.0"
  }
}
```

### **Integração com Arbo-CRM**
- Usar `@horizon-modules/arbo-crm-integration` para baixar dados
- Converter dados Arbo para PropertyModel usando `convertArboToPropertyV3`
- Aplicar validação Zod para garantir conformidade

## 📝 Formato PropertyModel

### **Estrutura Final**
```typescript
interface PropertyModel {
  reference: string
  title: string
  description: string
  attributes: Record<string, any>
  media_assets: {
    images: ImageMedia[]
    videos: VideoMedia[]
    virtual_tours: VirtualTourMedia[]
    documents: DocumentMedia[]
  }
  settings?: {
    currency_unit?: "BRL" | "USD"
    area_unit?: "m2" | "ft2"
    distance_unit?: "km" | "mi" | "meters"
    exibir_no_mapa?: boolean
  }
  updated_at?: string
}
```

### **Imagens do Unsplash**
```typescript
interface ImageMedia {
  full: string      // URL completa do Unsplash
  md?: string       // Versão 640x480
  sm?: string       // Versão 320x240
  cover?: boolean   // Se é a imagem principal
}
```

## 🏗️ Arquitetura dos Serviços

### **ArboDownloaderService**
```typescript
class ArboDownloaderService {
  async downloadAndConvert(options: {
    startPage: number
    endPage: number
    outputDir: string
  }): Promise<PropertyModel[]>
  
  async convertArboToPropertyModel(arboData: any): PropertyModel
}
```

### **ProfilerService** 
```typescript
class ProfilerService {
  async profileProperties(inputDir: string): Promise<ProfileResult>
  
  interface ProfileResult {
    [fieldName: string]: any[] // Valores únicos encontrados
  }
}
```

### **FakeDataGeneratorService**
```typescript
class FakeDataGeneratorService {
  constructor(config: {
    profilePath?: string
    outputDir: string
    count: number
    useUnsplash: boolean
  })
  
  async generate(): Promise<Record<string, PropertyModel[]>>
}
```

### **MockGeneratorService**
```typescript
class MockGeneratorService {
  constructor(config: {
    profilePath?: string
    outputDir: string
    validCount: number
    problematicCount: number
  })
  
  async generate(): Promise<{
    valid: PropertyModel[]
    problematic: PropertyModel[]
  }>
}
```

## 📊 Fluxo de Dados

```mermaid
graph TD
    A[Arbo CRM API] --> B[ArboDownloaderService]
    B --> C[__dev__/data/arbo-downloads/]
    C --> D[ProfilerService]
    D --> E[__dev__/data/profiling-report.json]
    E --> F[FakeDataGeneratorService]
    E --> G[MockGeneratorService]
    F --> H[__dev__/data/fake-data-output/]
    G --> I[__dev__/data/mock-output/]
    H --> J[Seleção Manual]
    J --> K[src/data/fake-data/]
    K --> L[NPM Package Export]
```

## 🧪 Estratégia de Testes

### **Testes Isolados**
- Todos os testes usam pastas temporárias
- Nenhum teste escreve em `/src/data`
- Cleanup automático após cada teste

### **Mock de APIs**
- Testes não fazem chamadas reais para Arbo CRM
- Usar dados estáticos para testes

### **Validação Zod**
- Todos os dados gerados devem passar na validação
- Testes verificam conformidade com PropertyModel

## 🚀 Scripts de Desenvolvimento

### **package.json scripts**
```json
{
  "scripts": {
    "dev:download": "tsx __dev__/scripts/download-from-arbo.ts",
    "dev:profile": "tsx __dev__/scripts/profile-properties.ts", 
    "dev:fake": "tsx __dev__/scripts/generate-fake-data.ts",
    "dev:mocks": "tsx __dev__/scripts/generate-mocks.ts",
    "dev:all": "npm run dev:download && npm run dev:profile && npm run dev:fake && npm run dev:mocks"
  }
}
```

## 📦 Exportação NPM

### **Dados Exportados**
```typescript
// src/index.ts
export { fakeProperties } from "./data/fake-data"
export { exampleProperties } from "./data/examples" 
export { profilingData } from "./data/profiling"
```

### **Estrutura Final do Pacote**
```
dist/
├── index.js
├── index.d.ts
└── data/
    ├── fake-data/
    ├── examples/
    └── profiling/
```

---

## ✅ Benefícios da Nova Arquitetura

1. **Dados Realistas**: Baseados em dados reais do Arbo CRM
2. **Profiling Inteligente**: Geração baseada em análise estatística
3. **Testes Robustos**: Isolados e com cleanup automático
4. **Desenvolvimento Eficiente**: Scripts automatizados para todas as etapas
5. **Qualidade Garantida**: Validação Zod em todos os dados gerados
6. **Flexibilidade**: Fácil atualização dos dados fake
7. **Performance**: Dados estáticos pré-gerados no NPM
8. **Manutenibilidade**: Estrutura clara e documentada

---

*Documentação gerada em: 2025-07-08*