@horizon-apps/domain-schema-core/docs/__domain-data-schema-specification.md

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

# 🏗️ SSOT (Single Source of Truth) - Especificação v2.0

## 📋 Visão Geral

O novo formato SSOT v2.0 organiza metadados de campos em **contextos específicos**, permitindo separação clara de responsabilidades e melhor organização dos dados.

### Filosofia do Formato
- **Contextos Separados**: Cada tipo de metadado tem seu lugar específico
- **Estrutura Hierárquica**: Agrupamento lógico das propriedades
- **Flexibilidade**: Campos podem ser vazios e preenchidos conforme necessário
- **Evolução Gradual**: Estrutura permite crescimento sem quebrar compatibilidade

---

## 🏗️ Estrutura dos Contextos

### 1. **RAIZ** - Identificação Básica
```typescript
{
  "key": "campo_exemplo",           // Identificador único (snake_case)
  "type": "String",                 // Tipo de dado (String, Number, Boolean, String[], Json)
  "enum": {"key": "Label"},         // Valores possíveis (quando aplicável)
  "format": "currency",             // Formatação de exibição
  "unit": "BRL",                    // Unidade de medida
  "categories": ["valores"]         // Tags/categorias para filtros
}
```

### 2. **RULES** - Regras e Relações
```typescript
"rules": {
  "parent": "tipo",                 // Campo pai hierárquico
  "conditions": ["operacao:venda"]  // Condições de visibilidade
}
```

### 3. **VALIDATION** - Validação Backend/Zod
```typescript
"validation": {
  "required": true,                 // Campo obrigatório
  "min": 0,                        // Valor mínimo (números)
  "max": 999999.99,                // Valor máximo (números)
  "minLength": 3,                  // Tamanho mínimo (strings)
  "maxLength": 200,                // Tamanho máximo (strings)
  "precision": 2                   // Casas decimais
}
```

### 4. **DB** - Configurações de Banco
```typescript
"db": {
  // VAZIO por enquanto - será preenchido conforme necessário
  // Futuro: index, unique, default, etc.
}
```

### 5. **UI** - Interface e Experiência
```typescript
"ui": {
  "label": "Campo Exemplo",        // Rótulo para exibição
  "description": "Texto de ajuda", // Helper text para formulários
  "placeholder": "Digite...",      // Placeholder para inputs
  "icon": "home",                  // Ícone semântico
  "displayTemplate": "{{value}} m²", // Template de exibição
  "mask": "cpf",                   // Máscara de input (cpf, cnpj, cep, phone, email)
  "searchable": true,              // Pesquisável por texto
  "filterable": true,              // Aparece nos filtros
  "sortable": true                 // Permite ordenação
}
```

### 6. **AUDIT** - Auditoria e Rastreamento
```typescript
"audit": {
  "origin": "horizon-base/imovel", // Origem do campo
  "modifiedBy": ["system"]         // Histórico de modificações
}
```

---

## 📚 Tipos de Dados Suportados

| Tipo | Descrição | Exemplo |
|------|-----------|---------|
| `String` | Texto simples | "Casa no Centro" |
| `Number` | Números inteiros e decimais | 150000.50 |
| `Boolean` | Verdadeiro/Falso | true, false |
| `String[]` | Array de strings | ["piscina", "churrasqueira"] |
| `Json` | Objeto JSON | {"lat": -27.5, "lng": -48.5} |
| `Json[]` | Array de objetos | [{"url": "...", "caption": "..."}] |

---

## 🎨 Formatos de Exibição

| Format | Unit | Exemplo Entrada | Exemplo Saída |
|--------|------|----------------|---------------|
| `currency` | `BRL` | 150000 | R$ 150.000,00 |
| `currency` | `USD` | 150000 | $ 150,000.00 |
| `area` | `m2` | 150 | 150 m² |
| `distance` | `km` | 1.5 | 1,5 km |
| `percent` | - | 0.15 | 15% |
| `count` | - | 3 | 3 itens |
| `date` | - | "2024-01-01" | 01/01/2024 |
| `datetime` | - | "2024-01-01T10:30:00Z" | 01/01/2024 10:30 |

---

## 🏷️ Categorias Recomendadas

| Categoria | Descrição | Campos Típicos |
|-----------|-----------|----------------|
| `valores` | Campos monetários | valor_venda, valor_locacao |
| `localizacao` | Endereço e geolocalização | endereco_cidade, latitude, longitude |
| `estrutura` | Características físicas | quartos, banheiros, area_total |
| `identificacao` | Títulos e referências | title, reference |
| `comercial` | Informações comerciais | operacao, status |
| `caracteristicas` | Amenidades e comodidades | piscina, churrasqueira |
| `sistema` | Campos internos | id, created_at, updated_at |

---

## 🔧 Máscaras Disponíveis

### Automáticas (inferidas do format + unit)
- `currency-brl` → R$ 1.000,00 (format: currency + unit: BRL)
- `currency-usd` → $ 1,000.00 (format: currency + unit: USD)
- `area` → 100 m² (format: area + unit: m2)
- `distance` → 1,5 km (format: distance + unit: km)
- `percent` → 15% (format: percent)
- `date` → DD/MM/AAAA (format: date)

### Explícitas (para casos específicos)
- `cpf` → 000.000.000-00
- `cnpj` → 00.000.000/0000-00
- `cep` → 00000-000
- `phone` → (00) 00000-0000
- `email` → Validação de email

---

## 📏 Condições de Visibilidade

### Operadores Disponíveis

| Operador | Descrição | Exemplo |
|----------|-----------|---------|
| `:` (padrão) | Contém | `"operacao:venda"` |
| `.equals` | Igual a | `"tipo.equals:apartamento"` |
| `.not` | Diferente de | `"status.not:vendido"` |
| `.in` | Está na lista | `"tipo.in:casa,apartamento"` |
| `.gt` | Maior que | `"valor.gt:100000"` |
| `.gte` | Maior ou igual | `"valor.gte:100000"` |
| `.lt` | Menor que | `"quartos.lt:5"` |
| `.lte` | Menor ou igual | `"area.lte:200"` |
| `.exists` | Campo preenchido | `"condominio.exists:true"` |

### Exemplos de Uso
```typescript
"rules": {
  "conditions": [
    "operacao:venda",              // operacao contém "venda"
    "tipo.equals:apartamento",     // tipo é exatamente "apartamento"
    "valor.gte:100000",            // valor >= 100000
    "quartos.in:2,3,4"             // quartos é 2, 3 ou 4
  ]
}
```

---

## 🌟 Exemplos Práticos

### Campo Simples
```json
{
  "key": "title",
  "type": "String",
  "categories": ["identificacao"],
  "validation": {
    "required": true,
    "minLength": 3,
    "maxLength": 200
  },
  "ui": {
    "label": "Título",
    "description": "Título do imóvel",
    "placeholder": "Ex: Casa no Centro",
    "searchable": true
  },
  "audit": {
    "origin": "horizon-base/imovel"
  }
}
```

### Campo com Enum
```json
{
  "key": "tipo",
  "type": "String",
  "enum": {
    "casa": "Casa",
    "apartamento": "Apartamento",
    "terreno": "Terreno"
  },
  "categories": ["estrutura"],
  "validation": {
    "required": true
  },
  "ui": {
    "label": "Tipo",
    "filterable": true,
    "sortable": true
  },
  "audit": {
    "origin": "horizon-base/imovel"
  }
}
```

### Campo Monetário
```json
{
  "key": "valor_venda",
  "type": "Number",
  "format": "currency",
  "unit": "BRL",
  "categories": ["valores"],
  "validation": {
    "min": 0,
    "max": 999999999.99,
    "precision": 2
  },
  "ui": {
    "label": "Valor de Venda",
    "displayTemplate": "{{value}}",
    "filterable": true,
    "sortable": true
  },
  "audit": {
    "origin": "horizon-base/imovel"
  }
}
```

### Campo com Condição
```json
{
  "key": "valor_locacao",
  "type": "Number",
  "format": "currency",
  "unit": "BRL",
  "categories": ["valores"],
  "rules": {
    "conditions": ["operacao:locacao"]
  },
  "validation": {
    "min": 0,
    "precision": 2
  },
  "ui": {
    "label": "Valor de Locação",
    "filterable": true,
    "sortable": true
  },
  "audit": {
    "origin": "horizon-base/imovel"
  }
}
```

---

## ⚡ Geração Automática

### Zod Schema
A partir do SSOT, é gerado automaticamente:
- Schema Zod para validação
- Tipos TypeScript inferidos
- Funções de validação (parse, safeParse, partial)

### Exemplo de Geração
```typescript
// Gerado automaticamente a partir do SSOT
export const ImovelZod = z.object({
  id: z.number().optional(),
  reference: z.string().min(1).max(50),
  title: z.string().min(3).max(200),
  tipo: z.enum(["casa", "apartamento", "terreno"]),
  valor_venda: z.number().min(0).multipleOf(0.01).optional()
})

export type ImovelType = z.infer<typeof ImovelZod>
```

---

## 🚀 Vantagens do Novo Formato

1. **Organização Clara**: Cada contexto tem seu espaço definido
2. **Flexibilidade**: Campos podem ser vazios e evoluir gradualmente  
3. **Separação de Responsabilidades**: UI, validação, DB em contextos isolados
4. **Manutenibilidade**: Fácil identificar onde cada metadado pertence
5. **Evolução**: Adicionar novos contextos sem quebrar existentes
6. **Reuso**: Mesmo campo pode ter comportamentos diferentes por contexto

---

## 📋 Checklist de Criação

### Campo Mínimo Obrigatório
- [ ] `key` - Identificador único
- [ ] `type` - Tipo de dado  
- [ ] `ui.label` - Rótulo para exibição
- [ ] `audit.origin` - Origem do campo

### Campo Típico (recomendado)
- [ ] Validação básica (`required`, limites)
- [ ] Categoria para organização
- [ ] Formatação quando aplicável
- [ ] Configurações de UI (searchable, filterable)

### Campo Complexo
- [ ] Enum quando valores limitados
- [ ] Condições de visibilidade
- [ ] Display template customizado
- [ ] Relacionamentos hierárquicos

---

Esta especificação serve como **base definitiva** para criação de schemas SSOT v2.0 no sistema, garantindo consistência, flexibilidade e evolução controlada dos metadados.