@horizon-apps/domain-schema-core/docs/REFATORACAO-HARDCODE.md

Core domain schema utilities for Horizon Platform - Schema generators, data enrichers, converters and specifications

# 🛠️ DOC DE REFATORAÇÃO - REMOÇÃO DE HARDCODES

> **Objetivo**: Tornar o Domain Display Enricher 100% agnóstico, removendo todos os hardcodes e assumptions sobre domínios específicos.

---

## 📋 **ANÁLISE ATUAL DOS HARDCODES**

### **🚫 PROBLEMA 1: Função `detectDomainFromData()`** 
**Local**: `domain-enricher-engine.ts:209-250`

**Hardcodes identificados:**
```typescript
// LINHA 213-226: Mapeamento fixo
const fieldToDomainMap: Record<string, string> = {
    "broker": "broker",        // ❌ HARDCODE
    "brokers": "broker",       // ❌ HARDCODE  
    "property": "property",    // ❌ HARDCODE
    "properties": "property",  // ❌ HARDCODE
    "image": "image",          // ❌ HARDCODE
    "images": "image",         // ❌ HARDCODE - PROBLEMA PRINCIPAL
    "user": "user",            // ❌ HARDCODE
    "users": "user",           // ❌ HARDCODE
    "owner": "user",           // ❌ HARDCODE
    "agent": "broker",         // ❌ HARDCODE
    "realtor": "broker",       // ❌ HARDCODE
};

// LINHA 242-244: Detecção por propriedades
if (data.creci) return "broker";                    // ❌ HARDCODE
if (data.cpf || data.cnpj) return "user";           // ❌ HARDCODE
if (data.url && (data.caption || data.alt)) return "image"; // ❌ HARDCODE
```

### **🚫 PROBLEMA 2: Registry fake nos testes**
**Local**: `tests/enricher.test.ts:301-313`

```typescript
registry = {
    property: { key: "property", enrichMapper: propertyEnrichMapperFake },
    broker: { key: "broker", enrichMapper: brokerEnrichMapperFake },
    image: { key: "image", enrichMapper: imageEnrichMapperFake }, // ❌ HARDCODE
}
```

### **🚫 PROBLEMA 3: Testes assumindo relacionamentos**
**Local**: `tests/enricher.test.ts:690-740`

```typescript
it("deve enriquecer array de relacionamentos (images)", () => {
    // ❌ Assume que images é relacionamento
    // ❌ Assume que existe domínio "image"
})
```

---

## 🎯 **PLANO DE REFATORAÇÃO DETALHADO**

### **ETAPA 1: Remover função `detectDomainFromData()` [SEM QUEBRAR TESTES]**

#### **1.1 Localizar onde é chamada:**
- `domain-enricher-engine.ts:154` (dentro de `processRelationshipField`)

#### **1.2 Substituir chamada por lógica simples:**
```typescript
// ANTES (hardcode):
const detectedDomain = this.detectDomainFromData(fieldKey, relationship);

// DEPOIS (agnóstico):
const detectedDomain = this.registry[fieldKey] ? fieldKey : null;
```

#### **1.3 Remover função completa:**
- Deletar linhas 209-250 inteiras
- Manter comportamento: só processar relacionamento se domínio existir no registry

### **ETAPA 2: Modificar lógica de relacionamentos [SEM QUEBRAR TESTES]**

#### **2.1 Simplificar `processRelationshipField()`:**
```typescript
// LÓGICA ATUAL (complexa):
// 1. Detecta se é relacionamento via isRelationship()
// 2. Chama detectDomainFromData() (hardcode)
// 3. Processa se encontrou domínio

// LÓGICA NOVA (simples):
// 1. Detecta se é relacionamento via isRelationship()
// 2. Verifica se fieldKey existe no registry
// 3. Processa se existe, senão ignora (deixa campo original)
```

#### **2.2 Impacto nos testes:**
- ✅ Testes de `broker` continuam funcionando (se `broker` estiver no registry)
- ❌ Testes de `images` vão falhar (pois `image` será removido do registry)
- ✅ Demais testes continuam normais

### **ETAPA 3: Ajustar registry fake dos testes [VAI QUEBRAR ALGUNS TESTES]**

#### **3.1 Remover domínio `image` do registry:**
```typescript
// ANTES:
registry = {
    property: { key: "property", enrichMapper: propertyEnrichMapperFake },
    broker: { key: "broker", enrichMapper: brokerEnrichMapperFake },
    image: { key: "image", enrichMapper: imageEnrichMapperFake }, // ← REMOVER
}

// DEPOIS:
registry = {
    property: { key: "property", enrichMapper: propertyEnrichMapperFake },
    broker: { key: "broker", enrichMapper: brokerEnrichMapperFake },
    // image removido - images agora é campo normal
}
```

#### **3.2 Testes que VÃO QUEBRAR (intencionalmente):**
- `"deve enriquecer array de relacionamentos (images)"` - ❌ DEVE quebrar
- Qualquer teste que assume `images` como relacionamento - ❌ DEVE quebrar

### **ETAPA 4: Adicionar `images` como campo normal no schema [CONSERTAR TESTES]**

#### **4.1 Atualizar schema fake da property:**
```typescript
const propertySchemaFake: FieldMetadata[] = [
    // ... campos existentes
    {
        key: "images",
        type: "Json[]", // Array de objetos JSON
        ui: {
            label: "Imagens",
            description: "Lista de imagens do imóvel"
        }
    },
    {
        key: "main_image", 
        type: "Json",   // Objeto JSON
        ui: {
            label: "Imagem Principal",
            description: "Imagem de destaque do imóvel"
        }
    }
]
```

#### **4.2 Atualizar testes quebrados:**
```typescript
// ANTES (como relacionamento):
it("deve enriquecer array de relacionamentos (images)", () => {
    // assumia que images era relacionamento
})

// DEPOIS (como campo normal):
it("deve enriquecer campo images como Json[]", () => {
    const rawData = {
        images: [
            { md: "url1", sm: "url1", full: "url1", cover: true },
            { md: "url2", sm: "url2", full: "url2", cover: false }
        ]
    };
    
    const result = enricher.enrich(rawData, "property");
    
    // Verifica que images foi enriquecido como campo normal
    expect(result.images).toBeDefined();
    expect((result.images as EnrichedField).type).toBe("Json[]");
    expect((result.images as EnrichedField).value).toEqual(rawData.images);
})
```

### **ETAPA 5: Validação [NÃO DEVE QUEBRAR TESTES PRINCIPAIS]**

#### **5.1 Testes que DEVEM continuar passando:**
- ✅ Enriquecimento básico de campos
- ✅ Relacionamento com `broker` (se registry tiver)
- ✅ Campos computados
- ✅ includeMetadata
- ✅ getIcon
- ✅ type, format, unit na raiz
- ✅ Null handling

#### **5.2 Testes que DEVEM falhar inicialmente:**
- ❌ Testes específicos de `images` como relacionamento
- ❌ Qualquer teste que assume hardcode

#### **5.3 Após ajustes, todos devem passar:**
- ✅ Todos os testes principais
- ✅ Novos testes de `images` como campo Json[]

---

## 🧪 **ESTRATÉGIA DE VALIDAÇÃO SEM QUEBRAR**

### **Ordem de execução:**
1. **Rodar testes antes** - capturar estado baseline
2. **Implementar ETAPA 1** - remover detectDomainFromData()
3. **Rodar testes** - ver impacto (alguns devem quebrar)
4. **Implementar ETAPA 2** - simplificar relacionamentos  
5. **Implementar ETAPA 3** - ajustar registry
6. **Rodar testes** - ver quebras intencionais
7. **Implementar ETAPA 4** - consertar com images como campo normal
8. **Rodar testes** - todos devem passar

### **Rollback se necessário:**
- Git commit após cada etapa
- Se algo quebrar inesperadamente, rollback pontual

---

## 📊 **RESULTADO ESPERADO FINAL**

### **✅ BENEFÍCIOS:**
- Domain Display Enricher 100% agnóstico
- Sem assumptions sobre nomes de domínios
- `images` processado como campo normal (Json[])
- Relacionamentos baseados apenas no registry fornecido
- Código mais limpo e extensível

### **✅ COMPATIBILIDADE:**
- Todos os testes principais continuam passando
- Comportamento para campos normais inalterado
- Relacionamentos funcionam se configurados no registry
- API pública inalterada

### **✅ NOVOS COMPORTAMENTOS:**
- `images` como campo Json[] enriquecido normalmente
- `main_image` como campo Json enriquecido normalmente  
- Relacionamentos só se domínio estiver explícito no registry
- Sem detecção "mágica" de relacionamentos

---

## 🎯 **ESTA É A ESTRATÉGIA PERFEITA**

**Justificativa**: 
1. **Preserva testes principais** - nada quebra desnecessariamente
2. **Remove hardcodes gradualmente** - etapas controladas  
3. **Substitui comportamento hardcoded** - por lógica agnóstica
4. **Mantém API** - sem breaking changes
5. **Melhora arquitetura** - torna extensível e limpo

**Pronto para executar com segurança!** 🚀