@horizon-labs/property-model-v3/README.md

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

# @horizon-labs/property-model-v3

Sistema de modelos de propriedades imobiliárias v3 com atributos dinâmicos e mapeamento customizado.

## 📦 Instalação

```bash
npm install @horizon-labs/property-model-v3
# ou
pnpm add @horizon-labs/property-model-v3
# ou
yarn add @horizon-labs/property-model-v3
```

## 🚀 Uso Básico

```typescript
import { 
  PropertyType, 
  PropertyAttributesModel, 
  propertyV3CustomMapper 
} from '@horizon-labs/property-model-v3';

// Exemplo de propriedade
const property: PropertyType = {
  reference: "AP001",
  title: "Apartamento 2 quartos",
  description: "Lindo apartamento...",
  attributes: [
    { key: "dormitorios", value: 2 },
    { key: "banheiros", value: 1 },
    { key: "area_privativa", value: 65, unit: "m²" }
  ],
  media: { pictures: [], videos: [], tour360: [] },
  tags: "",
  updated_at: new Date().toISOString()
};
```

## 🏗️ Arquitetura

### Modelos Principais

#### PropertyType
Interface principal que define a estrutura de uma propriedade:
- `reference`: Código único da propriedade
- `title`: Título da propriedade  
- `description`: Descrição detalhada
- `attributes`: Array de atributos dinâmicos
- `media`: Fotos, vídeos e tour 360°
- `tags`: Tags separadas por espaço
- `updated_at`: Data da última atualização

#### Attribute
Estrutura de atributos dinâmicos:
- `key`: Chave do atributo (ex: "dormitorios")
- `value`: Valor do atributo
- `valueLabel`: Label formatado para exibição
- `type`: Tipo do dado ("Number", "String", "Boolean", "String[]")
- `unit`: Unidade de medida ("BRL", "m²", "m")
- `composedLabel`: Label composto com templates

### Sistema de Atributos

O módulo inclui **96 atributos pré-definidos** organizados em categorias:

#### Categorias Disponíveis
- **Comercial**: `operacao`, `status_comercial`, `financiavel`
- **Valores**: `valor_venda`, `valor_locacao`, `valor_condominio`
- **Localização**: `endereco_cidade`, `endereco_bairro`, `latitude`
- **Estrutura**: `tipo`, `area_privativa`, `dormitorios`
- **Dependências**: `dormitorios`, `banheiros`, `suites`, `vagas_garagem`

```typescript
import { PropertyAttributesModel } from '@horizon-labs/property-model-v3';

// Encontrar atributo específico
const dormitoriosAttr = PropertyAttributesModel.find(attr => attr.key === "dormitorios");
console.log(dormitoriosAttr);
// { key: "dormitorios", label: "Dormitórios", type: "Number", cat: "dependencias" }
```

## 🎛️ Custom Mapper

Sistema avançado de transformação e normalização de propriedades com regras condicionais.

### Exemplo de Uso

```typescript
import { propertyV3CustomMapper } from '@horizon-labs/property-model-v3';

const mapRules = {
  // Regras baseadas no tipo do imóvel
  attrTipoRules: {
    "Casa": [
      { fn: "upsertAttr", key: "tipo", value: "Casa/Sobrado" },
      { fn: "upsertAttr", key: "subtipo", value: "Casa" }
    ],
    "Apartamento": [
      { fn: "upsertAttr", key: "tipo", value: "Apartamento" },
      { fn: "upsertAttr", key: "subtipo", value: "Apartamento" }
    ]
  },
  
  // Regras baseadas em tags
  tagsRules: {
    "rural": [
      { fn: "addTags", list: ["zona-rural"] }
    ]
  }
};

const transformedProperty = propertyV3CustomMapper(property, mapRules);
```

### Ações Disponíveis

- **upsertAttr**: Adiciona ou atualiza atributo
- **removeAttr**: Remove atributo 
- **addTags**: Adiciona tags
- **removeTags**: Remove tags

### Operadores Condicionais

```typescript
const advancedRules = {
  attributesRules: [
    {
      key: "dormitorios",
      condition: { gte: 3 }, // >= 3
      rules: [
        { fn: "addTags", list: ["casa-grande"] }
      ]
    },
    {
      key: "operacao", 
      condition: { has_any: ["venda", "locacao"] },
      rules: [
        { fn: "upsertAttr", key: "disponivel", value: true }
      ]
    }
  ]
};
```

**Operadores suportados**: `eq`, `not_eq`, `has`, `has_any`, `not_has`, `gt`, `gte`, `lt`, `lte`

## 🛠️ Utilitários

### Verificação de Atributos
```typescript
import { verifyAttrKeyInPropertyV3Model } from '@horizon-labs/property-model-v3';

const attr = verifyAttrKeyInPropertyV3Model("dormitorios");
// Retorna o modelo do atributo se existir
```

### Mesclagem de Modelos
```typescript
import { mergePropertyAttributesModel } from '@horizon-labs/property-model-v3';

const customModel = mergePropertyAttributesModel(
  PropertyAttributesModel,
  [
    { key: "dormitorios", label: "Quartos" }, // Override
    { key: "piscina", label: "Piscina", type: "Boolean" } // Novo
  ]
);
```

### Ordenação de Atributos
```typescript
import { sortAttributes } from '@horizon-labs/property-model-v3';

const sorted = sortAttributes(attributes, ["order:asc", "label:desc"]);
```

### Formatação de Labels
```typescript
import { preparaAttrValueLabel } from '@horizon-labs/property-model-v3';

preparaAttrValueLabel(["venda", "locacao"]);
// Retorna: "venda e locacao"

preparaAttrValueLabel(["venda", "locacao", "temporada"]);  
// Retorna: "venda, locacao e temporada"
```

## 🧪 Sistema de Unidades

```typescript
import { unitListModel } from '@horizon-labs/property-model-v3';

// Unidades de área
unitListModel.area; // [{ key: "m²", label: "m²" }, ...]

// Unidades monetárias  
unitListModel.currency; // [{ key: "BRL", label: "R$", locale: "pt-BR" }]

// Unidades de comprimento
unitListModel.length; // [{ key: "m", label: "m" }, ...]
```

## 📝 Exemplos Práticos

### Transformação de Dados Externos
```typescript
// Dados vindos de API externa
const externalData = {
  tipo: "Casa de Condomínio",
  quartos: 3,
  price: 450000
};

// Normalização para padrão v3
const property = {
  reference: "EXT001",
  attributes: [
    { key: "tipo", value: externalData.tipo },
    { key: "dormitorios", value: externalData.quartos },
    { key: "valor_venda", value: externalData.price, unit: "BRL" }
  ],
  // ... outros campos
};

const rules = {
  attrTipoRules: {
    "Casa de Condomínio": [
      { fn: "upsertAttr", key: "tipo", value: "Casa/Sobrado" },
      { fn: "upsertAttr", key: "subtipo", value: "Casa" },
      { fn: "addTags", list: ["em-condominio"] }
    ]
  }
};

const normalized = propertyV3CustomMapper(property, rules);
```

### Busca e Filtragem
```typescript
// Encontrar atributos por categoria
const valorFields = PropertyAttributesModel.filter(attr => attr.cat === "valores");

// Encontrar atributos com unidade específica
const areaFields = PropertyAttributesModel.filter(attr => attr.unit === "m²");
```

## 🏗️ TypeScript

Módulo totalmente tipado com interfaces exportadas:

```typescript
import type { 
  PropertyType,
  Attribute, 
  PropertyAttribute,
  PropertyObject,
  MapRules,
  MapAction 
} from '@horizon-labs/property-model-v3';
```

## 🧪 Testes

O módulo inclui testes abrangentes:

```bash
pnpm test        # Executa todos os testes
pnpm test:coverage # Executa com cobertura
```

## 📄 Licença

MIT - veja [LICENSE](LICENSE) para detalhes.

---

**Desenvolvido pela Horizon Labs** 🏗️