@horizon-apps/domain-schema-core/docs/index.md

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

# 📚 Domain Schema Core - Documentação (v1.2.8)

Índice completo da documentação dos sistemas integrados.

## 🚀 **Sistemas Principais**

### **🔍 PostgreSQL Search SQL Builder**
- **Localização**: [`src/postgre-search-sql-builder/README.md`](../src/postgre-search-sql-builder/README.md)
- **Descrição**: Sistema modular para geração de SQLs PostgreSQL complexos com Filter Engine integrado
- **Funcionalidades**: Filter Engine, ListBuilder (único registrado), Schema-aware, CTE optimized
- **Status**: ✅ Produção (v1.2.8) - ListBuilder: 31 testes passando

### **🌐 Search State to URL Parser**  
- **Localização**: [`src/search-state-to-url-parser/docs/README.md`](../src/search-state-to-url-parser/docs/README.md)
- **Descrição**: Sistema genérico de URLs SEO-friendly integrado com PostgreSQL Search SQL Builder
- **Funcionalidades**: URLs transparentes, Field mapping, Round-trip testado, Adapter pattern
- **Status**: ✅ Produção (v1.2.8) - 25 testes passando

## 🔗 **Integração Completa**

### **🎯 Pipeline URL ↔ SQL**
- **Localização**: [`docs/integration-complete.md`](./integration-complete.md)
- **Descrição**: Documentação completa do pipeline desde URLs SEO-friendly até SQLs PostgreSQL otimizados
- **Pipeline**: Frontend State → URL Builder → Search Adapter → SQL Builder → PostgreSQL
- **Status**: ✅ Totalmente integrado (v1.2.8) - 56 testes passando

## 📋 **Documentação Técnica**

### **Interfaces e Tipos**
- **PostgreSQL SQL Builder**: [`src/postgre-search-sql-builder/shared/interfaces.ts`](../src/postgre-search-sql-builder/shared/interfaces.ts)
- **URL Parser**: [`src/search-state-to-url-parser/search-to-url-query-serializer/index.ts`](../src/search-state-to-url-parser/search-to-url-query-serializer/index.ts)
- **Adapter**: [`src/search-state-to-url-parser/url-to-search-adapter/index.ts`](../src/search-state-to-url-parser/url-to-search-adapter/index.ts)

### **Testes de Integração**
- **Pipeline Completo**: [`src/search-state-to-url-parser/__tests__/integration-complete.test.ts`](../src/search-state-to-url-parser/__tests__/integration-complete.test.ts)
- **Database Testing**: [`src/postgre-search-sql-builder/examples/04-database-testing.ts`](../src/postgre-search-sql-builder/examples/04-database-testing.ts)

## 🧰 **APIs Principais**

### **Função de Conveniência - SQL Builder**
```typescript
import { createSQLBuilder } from '@horizon-apps/domain-schema-core';

const sqlBuilder = createSQLBuilder({ 
  schema: createTestPropertySchema(),
  logging: true 
});
```

### **Função de Conveniência - URL Builder**
```typescript
import { SearchUrlBuilder } from '@horizon-apps/domain-schema-core/search-state-to-url-parser';

const urlBuilder = new SearchUrlBuilder({
  rootUrl: '/imoveis/',
  enableSlug: true
});
```

### **Função de Conveniência - Adapter**
```typescript
import { createImoveisAdapter } from '@horizon-apps/domain-schema-core/url-to-search-adapter';

const adapter = createImoveisAdapter();
```

## 🎯 **Casos de Uso Principais**

### **1. Busca Imobiliária Completa**
```typescript
// Estado Frontend → URL → SQL
const searchState = {
  filters: { tipo: 'Casa', cidade: 'Curitiba' },
  search: 'casa moderna',
  page: 1,
  limit: 20
};

// Pipeline automático: State → URL → Adapter → SQL
const result = executeCompleteSearch(searchState);
```

### **2. Mapa Interativo (EM DESENVOLVIMENTO)**
```typescript
// MapBuilder não está registrado no orchestrator
const mapRequest = {
  filters: { tipo: ['Casa', 'Apartamento'] },
  include: ['list'],  // Apenas ListBuilder disponível
  list: { page: 1, limit: 50 }
};
```

### **3. Facetas para Interface (EM DESENVOLVIMENTO)**
```typescript
// FacetsBuilder não está registrado no orchestrator  
const facetRequest = {
  filters: { cidade: 'São Paulo' },
  include: ['list'],  // Apenas ListBuilder disponível
  list: { page: 1, limit: 20 }
};
```

## 🧪 **Execução de Testes**

### **Todos os Testes**
```bash
# Executar todos os testes do sistema
pnpm test

# Testes específicos
pnpm test search-state-to-url-parser    # 25 testes
pnpm test postgre-search-sql-builder    # 31 testes
pnpm test integration-complete          # Pipeline completo
```

### **Testes com Database Real**
```bash
# Exemplo com PostgreSQL real
pnpm tsx src/postgre-search-sql-builder/examples/04-database-testing.ts
```

## 📊 **Status dos Sistemas**

| Sistema | Versão | Testes | Status | Documentação |
|---------|--------|--------|--------|--------------|
| PostgreSQL SQL Builder | v1.2.8 | 31/31 ✅ | Produção | ✅ Completa |
| Search URL Parser | v1.2.8 | 25/25 ✅ | Produção | ✅ Completa |
| Pipeline Integração | v1.2.8 | 56/56 ✅ | Produção | ✅ Completa |
| **TOTAL** | **v1.2.8** | **56/56 ✅** | **Produção** | **✅ Completa** |

## 🎉 **Principais Conquistas v1.2.8**

✅ **Search Field Separado** - `search` field fora de `filters` para melhor arquitetura  
✅ **Pipeline Completo** - URL ↔ SQL Builder totalmente integrado e funcionando  
✅ **Field Mapping** - Sistema de mapeamento configurável de campos  
✅ **Filter Engine** - Processamento inteligente: Geospatial, Arrays, Ranges  
✅ **Testes Completos** - 56 testes passando, incluindo integração end-to-end  
✅ **Documentação Atual** - Redocumentação completa refletindo estado real  
✅ **TypeScript Zero Errors** - 0 erros TypeScript após limpeza completa (28→0)  
✅ **Fulltext Nativo Apenas** - Removido fuzzy/hybrid, apenas vector (websearch_to_tsquery)  
✅ **APIs Simplificadas** - Parâmetros desnecessários removidos, assinaturas limpas  
✅ **Performance** - CTEs, execução paralela e otimizações PostgreSQL  

---

**🚀 Sistema completo pronto para produção!** 

Para usar os sistemas, comece pela [documentação de integração](./integration-complete.md) que mostra o pipeline completo.