@horizon-framework/api-nextjs-docs 2.3.0

package/docs/BATCH_TOTALS_API.md

@@ -0,0 +1,200 @@
+# Batch Totals API - Menu Dinâmico com Performance
+
+## **Problema Resolvido**
+
+**Cenário:** Menu de navegação em site imobiliário
+```
+IMÓVEIS
+├── Apartamento 2 quartos (845) ← precisa do total
+├── Apartamento 3 quartos (723)
+├── Casa 2 quartos (400) 
+├── Casa 3 quartos (169)
+└── ... mais 12 categorias
+```
+
+**Solução Ruim:** 16 requests HTTP separados
+**Solução Inteligente:** 1 request com array de queries
+
+## **Performance**
+
+| Abordagem | HTTP Calls | Tempo | Eficiência |
+|-----------|------------|-------|------------|
+| **Múltiplos requests** | 16 | ~2.3s | Lento |
+| **Batch Totals** | 1 | ~250ms | 90% mais rápido |
+
+## **API Specification**
+
+### **Endpoint:**
+```
+POST /api/property/batch-totals
+```
+
+### **Request Format:**
+```json
+{
+  "queries": [
+    {
+      "key": "apartamento_2q",
+      "filters": { 
+        "tipo": "Apartamento", 
+        "dormitorios": 2 
+      },
+      "meta": { "total": true }
+    },
+    {
+      "key": "casa_3q", 
+      "filters": {
+        "tipo": "Casa",
+        "dormitorios": 3
+      },
+      "meta": { "total": true }
+    }
+  ]
+}
+```
+
+### **Response Format:**
+```json
+{
+  "results": {
+    "apartamento_2q": { "total": 845 },
+    "casa_3q": { "total": 169 }
+  },
+  "metadata": {
+    "executionTime": 245,
+    "queriesProcessed": 2,
+    "parallelExecution": true
+  }
+}
+```
+
+## **Implementação Técnica**
+
+### **Arquitetura:**
+```
+Controller → Service → Promise.all() → advancedSearch() × N
+```
+
+### **Características:**
+- **Execução paralela** com `Promise.all()`
+- **Keys únicas** para cada query
+- **Filtros flexíveis** (qualquer combinação)
+- **Error handling** individual por query
+- **Performance logs** automáticos
+
+## **Casos de Uso**
+
+### **1. Menu de Navegação**
+```javascript
+const menuQueries = [
+  { key: "apt_2q", filters: { tipo: "Apartamento", dormitorios: 2 } },
+  { key: "apt_3q", filters: { tipo: "Apartamento", dormitorios: 3 } },
+  { key: "casa_2q", filters: { tipo: "Casa", dormitorios: 2 } }
+];
+```
+
+### **2. Dashboard com Métricas**
+```javascript
+const dashboardQueries = [
+  { key: "total_ativos", filters: { status: "ativo" } },
+  { key: "total_vendidos", filters: { status: "vendido" } },
+  { key: "total_premium", filters: { destaque: true } }
+];
+```
+
+### **3. Filtros Dinâmicos**
+```javascript
+const filterCounts = [
+  { key: "por_cidade", filters: { endereco_cidade: "Florianópolis" } },
+  { key: "por_preco", filters: { valor_venda: { gte: 500000 } } },
+  { key: "com_piscina", filters: { caracteristicas: { contains: "Piscina" } } }
+];
+```
+
+## **Frontend Integration**
+
+### **Next.js Static Props:**
+```typescript
+export async function getStaticProps() {
+  const response = await fetch('/api/property/batch-totals', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ queries: MENU_QUERIES })
+  });
+  
+  const { results } = await response.json();
+  
+  return {
+    props: { menuCounters: results },
+    revalidate: 7200 // Cache 2h
+  };
+}
+```
+
+### **SWR Client-Side:**
+```typescript
+import useSWR from 'swr';
+
+const { data: counters } = useSWR(
+  'menu-counters',
+  () => batchTotals(MENU_QUERIES),
+  { refreshInterval: 300000 } // 5min
+);
+```
+
+## **Limitações & Considerações**
+
+### **Limites:**
+- **Máximo:** 20 queries por request
+- **Timeout:** 30 segundos total
+- **Cache:** Recomendado 1-4 horas
+
+### **Error Handling:**
+```json
+{
+  "results": {
+    "valid_query": { "total": 845 },
+    "invalid_query": { "error": "Campo inválido", "total": 0 }
+  }
+}
+```
+
+### **Performance Tips:**
+- Cache no cliente (SWR/React Query)
+- Cache no servidor (Redis)
+- Revalidação com webhooks
+- Não usar para queries complexas
+
+## **Exemplo Completo**
+
+### **Request Real:**
+```bash
+curl -X POST http://localhost:5000/api/property/batch-totals \
+  -H "Content-Type: application/json" \
+  -d '{
+    "queries": [
+      {
+        "key": "apartamento_2q",
+        "filters": { "tipo": "Apartamento", "dormitorios": 2 },
+        "meta": { "total": true }
+      }
+    ]
+  }'
+```
+
+### **Response Real:**
+```json
+{
+  "results": {
+    "apartamento_2q": { "total": 845 }
+  },
+  "metadata": {
+    "executionTime": 156,
+    "queriesProcessed": 1
+  }
+}
+```
+
+---
+
+**Batch Totals API - Solução definitiva para menus dinâmicos com performance!**

package/docs/DOMINIO_ENTIDADES.md

@@ -0,0 +1,328 @@
+# Domínio e Entidades — Modelos de Dados Ponta a Ponta
+
+> Arquitetura de dados dos módulos Horizon: como os modelos de entidades são definidos, transformados e consumidos em cada camada da aplicação — do CRM externo ao pixel na tela.
+> Genérico para qualquer módulo (property, broker, etc.) e qualquer CRM.
+
+---
+
+## CONCEITO
+
+O Horizon trabalha com **módulos de domínio**. Cada módulo (property, broker, etc.) segue a mesma arquitetura de dados em 3 camadas:
+
+### As 17 camadas do fluxo de dados
+
+**ROOT (genérica, qualquer entidade):**
+1. DB System — id, created_at, updated_at, first_synced_at, sync_raw_data
+2. Generated Columns SQL — fts_vector (fulltext), geom (PostGIS)
+3. Relations — relações virtualizadas (ex: broker → Broker.key)
+
+**HORIZON BASE (universal):**
+4. Campos base do domain model (ex: 45 campos property)
+5. Computed base — derivados diretos da base (seo_slug_gen, thumbnails, endereco_completo)
+
+**CRM (muda por integração):**
+6. Extras CRM — campos específicos do CRM no banco
+7. Transformações CRM — dataModifier rules + computed customizados
+
+**SYNC (entrada):**
+8. PUT /api/[entity]/sync — recebe dados do conversor
+9. Validação + Transformações — Zod + rules + computed (pipeline)
+
+**PRISMA (ponte):**
+10. db pull → patch-relations → generate
+
+**SCHEMA (SSOT):**
+11. entity-schema.ts + API endpoint
+
+**FRONTEND:**
+12. prebuild → schema.generated.json
+13. Computed Frontend — URL + flags layout (assembleComputedData)
+14. fields-lists.ts — seções customizadas de atributos
+15. select-fields.config.ts — campos do card
+
+**BUSCA:**
+16. Search schema + config — filtros, facets, ranges, sort
+17. Filtros extras por CRM
+
+Cada módulo no backend e frontend segue a mesma estrutura:
+```
+[modulo]/
+├── core/        → Serviços, schemas, libs (FUNDAÇÃO)
+├── features/    → Features completas e autônomas
+└── customs/     → Customizações do site
+```
+
+---
+
+## FILOSOFIA HORIZON — DOMAIN MODELS
+
+O Horizon define um **modelo de domínio base** para cada entidade, publicado como pacote npm `@horizon-domains/[entidade]-model`. Este modelo é o contrato que TODOS os CRMs devem cumprir.
+
+### Pacotes de domínio existentes
+
+| Pacote | Entidade | Campos base | Local |
+|---|---|---|---|
+| `@horizon-domains/property-model` | Imóvel | 45 campos | `horizon-modules/property/domain-data` |
+| `@horizon-domains/broker-model` | Corretor | ~20 campos | `horizon-modules/broker/domain-data` |
+
+### Outros módulos Horizon (sem domínio de CRM)
+
+| Módulo | Função |
+|---|---|
+| `horizon-modules/blog` | Blog |
+| `horizon-modules/cidade-e-bairros` | Cidades e bairros |
+| `horizon-modules/condo` | Condomínios |
+| `horizon-modules/instagram-advanced` | Instagram avançado |
+
+### Como funciona
+
+1. **Campos base** — O domain model define campos OBRIGATÓRIOS que toda entidade deve ter (ex: property tem 45 campos: reference, title, description, tipo, operacao, dormitorios, etc.). Todo CRM PRECISA preencher esses campos.
+
+2. **Campos extras do CRM** — Cada CRM tem campos ADICIONAIS além da base. Esses excedentes são normalizados pelo pacote conversor seguindo regras de normalização:
+   - Ponto → underscore: `insurance.letter` → `insurance_letter`
+   - Hífen → underscore: `air-conditioner` → `air_conditioner`
+   - Objetos aninhados → prefixo: `features.room` → `features_room`
+   - Booleans agrupados → array TEXT[]: `features`, `security`, `recreation`, `rural`
+   - Tudo snake_case minúsculo
+
+3. **Schema final** — O entity-schema do site combina campos base (do domain model) + campos extras (do CRM) numa entidade única.
+
+```
+@horizon-domains/property-model (45 campos base)
+  + @horizon-integrations/[crm] (campos extras normalizados + enum labels)
+  = Entity Schema do site (base + extras + computed + relações)
+```
+
+4. **Enum labels** — Campos com valores fixos (enums) devem ter o mapa `enum: { VALOR: "Label PT-BR" }` definido **no pacote CRM**, não no site. O banco armazena a chave técnica (SOLD, RENTED, etc.) e o frontend traduz pra label legível via enricher usando o `enum` do schema.
+
+**REGRA:** Valores no banco = chaves técnicas (inglês). Labels de exibição = vêm do `enum` no schema (que vem do pacote CRM). NUNCA traduzir no conversor — isso quebraria filtros e facets.
+
+---
+
+## CAMADA 1 — PACOTE CONVERSOR (npm)
+
+Cada CRM tem um pacote npm `@horizon-integrations/[crm]` que:
+
+| Exporta | Função |
+|---|---|
+| Conversor | Transforma dados crus do CRM → formato Horizon padronizado (snake_case) |
+| Schema Zod | Validação dos dados convertidos |
+| EntitySchema | Schema da entidade com metadados (tipo, label, categoria, source tracking) |
+| FICHA_TECNICA_INTEGRACAO.md | Diretrizes completas: campos, tipos SQL, badges, filtros, transformações |
+
+**Base Horizon:** 45 campos padronizados que existem em QUALQUER CRM (reference, title, description, operacao, tipo, dormitorios, etc.). Definidos em `@horizon-domains/property-model`.
+
+**Extras CRM:** Campos específicos que cada CRM adiciona além da base (variam por CRM).
+
+---
+
+## CAMADA 2 — API (apps/api)
+
+### Sync (entrada de dados)
+```
+PUT /api/property/sync
+  → source-schema.zod.ts (validação Zod do pacote CRM)
+  → dataModifier/rules.ts (transformações Etapa 3: subtipo, tags→campos)
+  → computedFields/index.ts (campos calculados: slug, thumbnails, endereço, flags)
+  → Prisma INSERT/UPSERT → PostgreSQL
+```
+
+**Autenticação:** Header `x-api-key` com `API_SECRET_KEY` do `.env`
+**Batching:** Máximo ~50 imóveis por request (timeout Prisma = 5s)
+
+### Banco PostgreSQL
+- **create.sql** — Seções ordenadas: DB system → Horizon base (45) → Extras CRM → Computed → Etapa 3
+- **generated-columns.sql** — `fts_vector` (busca textual), `geom` (geoespacial)
+- **relations.ts** — Relações virtualizadas (injetadas via `pnpm db:patch-relations`)
+- **Índices** — B-tree (filtros), GIN (arrays + FTS), GIST (geom)
+
+### Entity Schema (SSOT)
+- **entity-schema.ts** — Define TODOS os campos da entidade com:
+  - `type` (String, Number, Boolean, Json, Relation)
+  - `categories` (ficha-tecnica, localizacao, media, etc.)
+  - `ui` (label, description, icon, displayTemplate)
+  - `relation` (model, field, labelField, displayTemplate, foreignKey)
+  - `audit` (origin: crm-base, crm-extra, computed, local-relation)
+- **Display Overrides** — Templates como `"{{valueLabel}} quarto{{p:s}}"`, ícones customizados
+- **Exposto via:** `GET /api/property/schemas/entity`
+
+### Search e Facets
+- **`POST /api/property/search`** — Busca multipart (filters, facets, fts, geom, list, map)
+- **`POST /api/property/batch-search`** — Múltiplas buscas em 1 request
+- **Facets** — Sistema automático de contagens agrupadas (terms, range, histogram)
+- **Enricher de relação** — Transforma key → label via lookup no modelo relacionado
+
+---
+
+## CAMADA 3 — FRONTEND (apps/web)
+
+### Schema no Frontend
+- **Geração:** `npx tsx scripts/generate-schema.ts` (API precisa estar rodando)
+- **Output:** `schema.generated.json` no módulo
+- **REGRA:** Sempre regenerar quando alterar entity-schema.ts na API
+
+### Data Display Enricher
+- **Função:** Transforma dados crus da API → formato de exibição
+- **Processo:** Lê `schema.generated.json` → aplica labels, formatos, ícones, templates → retorna objeto enriquecido
+- **Cada campo vira:** `{ key, value, valueLabel, label, type, icon, ... }`
+
+### PropertyService (core)
+Singleton `propertyService` com métodos:
+
+| Método | Uso |
+|---|---|
+| `search(request)` | Busca com filtros, facets, paginação |
+| `batchSearch(queries)` | Múltiplas buscas em 1 request (contagens, navegação) |
+| `find(criteria)` | Busca simples por critério |
+| `getDistinct(fields)` | Valores distintos (server-side, requer API_SECRET) |
+| `getEntitySchema()` | Schema SSOT da entidade |
+
+**Usos além de busca:** Contagens dinâmicas em cards, links, navegações, vitrines. Sempre usar com cache.
+
+### Fields Lists (core)
+`fields-lists.ts` — Funções getter que filtram e organizam campos pra cada contexto de exibição:
+- Cards: tarjas, badges, destaques com ícone, valores principais
+- Página: seções da ficha (principal, características, segurança, lazer, dimensões, rural, etc.)
+- Valores: caixa lateral (preços, taxas, flags comerciais)
+
+### Select Fields (core)
+`select-fields.config.ts` — Define quais campos buscar da API por contexto:
+- `full` — Todos os campos + relações
+- `cardList` — Campos necessários pro card (tarjas, badges, destaques, endereço, preço)
+- `mapList` — Apenas id, reference, lat, lng (pins do mapa)
+
+---
+
+## FLUXO DE ALTERAÇÃO
+
+### Alterar entity-schema.ts (displayOverrides, labels, etc.)
+1. Alterar arquivo na API
+2. Reiniciar API (Prisma Client cacheado em memória)
+3. Regenerar schema: `cd apps/web && npx tsx scripts/generate-schema.ts`
+
+### Alterar create.sql (colunas do banco)
+1. `db:drop` → `db:create` → `prisma db pull` → `db:patch-relations` → `prisma generate`
+2. Reiniciar API
+3. Re-sincronizar dados
+
+### Trocar CRM
+Ver checklist completa em `AGENTE_CONFIGURACAO_CRM.md`
+
+---
+
+## DATABASE (apps/api/database/)
+
+Sistema de gestão do banco PostgreSQL:
+
+```
+database/
+├── tables/
+│   ├── property/
+│   │   ├── create.sql              → Schema da tabela (CREATE TABLE)
+│   │   └── generated-columns.sql   → Colunas geradas (fts_vector, geom)
+│   ├── broker/
+│   │   └── create.sql
+│   └── branch/
+│       └── create.sql
+├── shared/                          → SQL compartilhado entre tabelas
+├── relations.ts                     → Definição de relações Prisma (injetadas)
+└── scripts/
+    ├── db-setup.ts                  → Setup inicial do banco
+    ├── table-create.ts              → Cria tabela a partir do create.sql
+    ├── table-drop.ts                → Dropa tabela
+    ├── patch-relations.ts           → Injeta relações no schema Prisma
+    └── sync-prisma.ts               → Sincroniza Prisma com banco
+```
+
+### Comandos de banco (via pnpm)
+| Comando | Função |
+|---|---|
+| `pnpm db:create [tabela]` | Cria tabela a partir do create.sql |
+| `pnpm db:drop [tabela]` | Dropa tabela |
+| `pnpm db:patch-relations` | Injeta relações no schema.prisma |
+| `npx prisma db pull` | Puxa schema do banco pro Prisma |
+| `npx prisma generate` | Gera Prisma Client |
+
+### Ordem obrigatória ao recriar tabela
+```
+db:drop → db:create → prisma db pull → db:patch-relations → prisma generate → REINICIAR API
+```
+**ORDEM IMPORTA:** `pull` ANTES de `patch-relations` (pull sobrescreve relações).
+
+---
+
+## MÓDULOS BACKEND (apps/api/src/modules/)
+
+Cada módulo segue a mesma estrutura:
+
+```
+modules/[modulo]/
+├── controllers/     → HTTP handlers (Next.js API routes)
+├── services/        → Lógica de negócio
+├── schemas/
+│   ├── source-schema.zod.ts   → Validação de entrada (Zod do CRM)
+│   └── entity-schema.ts       → Schema SSOT (tipo, label, icon, relações)
+├── mappers/
+│   ├── dataModifier/rules.ts       → Transformações na entrada
+│   └── computedFields/index.ts     → Campos calculados
+└── __tests__/       → Testes
+```
+
+Módulos existentes:
+
+| Módulo | Entidade | Controllers | Pacote de domínio |
+|---|---|---|---|
+| property | Imóvel | search, sync, batch-search, schemas | `@horizon-domains/property-model` |
+| broker | Corretor | search, sync, schemas | `@horizon-domains/broker-model` |
+
+---
+
+## LIB DE PESQUISA AVANÇADA (apps/api/src/lib/advancedSearch/)
+
+Sistema **100% genérico** de busca avançada usado por todos os módulos. Zero hardcodes de domínio.
+
+```
+advancedSearch/
+├── index.ts           → Entry point (advancedSearch function)
+├── types.ts           → Types do SearchRequest/SearchResult
+├── executeList.ts     → Executa query de listagem (paginação offset/cursor)
+├── executeMap.ts      → Executa query de mapa (todos os pontos)
+├── executeTotal.ts    → Executa contagem total
+├── extractIds.ts      → Extrai IDs de resultados
+├── helpers.ts         → Helpers de filtros, FTS, geom
+├── facets/            → Sistema de facetas
+│   ├── index.ts
+│   ├── facets.service.ts      → Orquestra execução de facetas
+│   ├── types.ts               → Types de facetas
+│   ├── enrichers/
+│   │   └── relation.ts        → Enricher de relações (key → label lookup)
+│   └── tests/
+└── docs/              → Documentação interna completa
+    └── facets/
+        ├── README.md                      → Índice
+        ├── facets-system-complete.md      → DOC PRINCIPAL E ATUALIZADA
+        ├── facets-objectives.md           → Visão original
+        └── facets-implementation-checklist.md
+```
+
+### Tipos de faceta suportados
+| Tipo | Uso | Exemplo |
+|---|---|---|
+| `terms` | Contagem por valor distinto | tipo, cidade, bairro, features[] |
+| `range` | Buckets customizados ou automáticos | valor_venda (faixas de preço) |
+| `histogram` | Buckets de distribuição visual | area_privativa (equal-depth) |
+
+### Enricher de relação
+Transforma automaticamente chaves estrangeiras em labels legíveis:
+- Detecta relação no entity-schema → faz lookup no modelo Prisma → retorna `{value, label, count}`
+- Exemplo: facet `broker` → `{value: "elvis-ghisi", label: "Elvis Ghisi", count: 1}`
+
+### Documentação interna
+Para detalhes completos do sistema de facetas, consultar:
+`apps/api/src/lib/advancedSearch/docs/facets/facets-system-complete.md`
+
+---
+
+## MÓDULOS EXISTENTES
+
+Cada módulo segue a mesma arquitetura descrita acima. Os conceitos de entity-schema, enricher, select fields e fields lists se aplicam a todos.