@horizon-framework/website-dev-docs 2.3.0

package/knowledge/ARQUITETURA_GERAL.md

@@ -0,0 +1,169 @@
+# Arquitetura Geral — Horizon Platform
+
+> Visao completa do projeto: 5 partes, 3 deploys Vercel, monorepo com pnpm.
+
+---
+
+## Estrutura do Projeto
+
+```
+raiz/
+├── apps/
+│   ├── web/           ← Frontend (Next.js 15, React 19, porta 3001)
+│   ├── api/           ← Backend API (Next.js 14, Prisma, porta 5000)
+│   └── automations/   ← Automacoes (Next.js 15, porta 8080)
+├── ai/                ← Cerebro do agente (docs NPM, config cliente)
+├── docs/              ← Docs especificas deste site/cliente
+├── dev/               ← Area de trabalho temporaria (screenshots, logs, rascunhos)
+├── CLAUDE.md          ← Prompt master do agente
+└── horizon.config.md  ← Prontuario do site (versao, cliente, CRM, modulos)
+```
+
+---
+
+## Os 3 Apps
+
+### WEB — Frontend (apps/web/)
+- **Framework:** Next.js 15.5.7 + React 19.1.0
+- **Porta dev:** 3001
+- **Stack:** Tailwind 4 + shadcn/ui + Framer Motion + Zustand + React Query
+- **Responsabilidade:** Todas as paginas do site, busca de imoveis, UI completa
+- **Build:** `NODE_OPTIONS='--max-old-space-size=4096' next build`
+- **Storybook:** porta 6006
+- **Email preview:** via React Email
+
+### API — Backend (apps/api/)
+- **Framework:** Next.js 14.2.32 + React 18.3.1
+- **Porta dev:** 5000
+- **Stack:** Prisma 6 + PostgreSQL (DigitalOcean) + PostGIS + Zod
+- **Responsabilidade:** API REST, busca multipart, sync com CRM, schemas SSOT
+- **Build output:** standalone
+- **Vercel region:** gru1 (Sao Paulo)
+- **Serverless max:** 30s
+
+### AUTOMATIONS — Integracoes (apps/automations/)
+- **Framework:** Next.js 15.5.7 + React 19.0.0
+- **Porta dev:** 8080
+- **Stack:** Resend (emails) + React Email + Zod
+- **Responsabilidade:** Receber leads, enviar emails, sincronizar com CRM
+- **CORS:** Configura domínios permitidos
+
+---
+
+## Fluxo de Comunicacao
+
+```
+Browser → WEB (3001) → API (5000) ← PostgreSQL + PostGIS
+                    ↘
+                 AUTOMATIONS (8080) → Resend (emails)
+                                   → CRM externo (Jetimob, SI9)
+```
+
+1. Usuario visita o site (WEB)
+2. WEB busca dados na API (imoveis, corretores, schemas)
+3. Usuario envia formulario → WEB envia lead para AUTOMATIONS
+4. AUTOMATIONS envia email via Resend + sincroniza com CRM
+
+---
+
+## Deploy Vercel
+
+Cada app e deployada separadamente na Vercel:
+- **WEB:** Site publico (dominio do cliente)
+- **API:** API endpoints (region gru1 - SP)
+- **AUTOMATIONS:** Endpoints de integracao
+
+Cada app tem seu `vercel.json` com:
+- framework: nextjs
+- installCommand: pnpm i
+- functions maxDuration: 30s
+
+---
+
+## Variaveis de Ambiente
+
+### WEB (.env.local)
+```
+API_SECRET_KEY=         # Chave da API
+ADMIN_PASSWORD=         # Senha admin (inspect)
+NEXT_PUBLIC_SITE_URL=   # URL do site (ex: http://localhost:3001)
+NEXT_PUBLIC_API_URL=    # URL da API (ex: http://localhost:5000)
+NEXT_PUBLIC_AUTOMATIONS_URL=  # URL automations (ex: http://localhost:8080)
+YOUTUBE_API_KEY=        # YouTube Data API v3
+```
+
+### API (.env)
+```
+DATABASE_URL=           # PostgreSQL connection string
+API_SECRET_KEY=         # Chave de autenticacao
+API_BASE_URL=           # URL da propria API
+FRONTEND_BASE_URL=      # URL do frontend
+```
+
+### AUTOMATIONS (.env.local)
+```
+API_SECRET_KEY=         # Chave da API
+RESEND_API_KEY=         # Chave do Resend (emails)
+JETIMOB_PUBLIC_KEY=     # CRM Jetimob
+JETIMOB_PRIVATE_KEY=    # CRM Jetimob
+NEXT_PUBLIC_API_URL=    # URL da API
+```
+
+---
+
+## Banco de Dados
+
+- **Provider:** PostgreSQL em DigitalOcean
+- **Porta:** 25061 (SSL required)
+- **ORM:** Prisma 6
+- **Extensoes:** PostGIS (geolocation), UUID-OSSP
+- **Models:** Property, Broker, Branch, spatial_ref_sys
+- **Features:** Full-text search (tsvector), busca geoespacial (geometry)
+
+---
+
+## Pasta /dev/
+
+Area de trabalho temporaria na raiz. Pode conter:
+- Screenshots de debug
+- Logs de teste
+- Arquivos temporarios de desenvolvimento
+- NAO e versionada com importancia (pode ser limpa)
+
+---
+
+## Pasta /ai/
+
+Cerebro do agente de IA. Contem:
+- `package.json` — instala pacotes de conhecimento via NPM
+- `horizon.config.md` — prontuario do site
+- `client/` — docs especificas deste cliente
+- `node_modules/` — docs da plataforma + modulos + integracoes
+
+---
+
+## Scripts Uteis
+
+```bash
+# Desenvolvimento
+cd apps/web && pnpm dev          # Frontend porta 3001
+cd apps/api && pnpm dev          # API porta 5000
+cd apps/automations && pnpm dev  # Automations porta 8080
+
+# Build
+cd apps/web && pnpm build
+cd apps/api && pnpm build
+
+# Banco de dados (API)
+cd apps/api && pnpm db:setup     # Setup inicial
+cd apps/api && pnpm db:create    # Criar tabelas
+cd apps/api && pnpm db:sync      # Sync Prisma
+cd apps/api && npx prisma generate  # Gerar client
+
+# Storybook
+cd apps/web && pnpm storybook    # Porta 6006
+
+# Email preview
+cd apps/web && pnpm email
+cd apps/automations && pnpm email
+```

package/knowledge/ARQUITETURA_MODULOS_WEB.md

@@ -0,0 +1,241 @@
+# Arquitetura de Módulos - WEB
+
+> Guia de estrutura padrão para módulos no frontend (`/apps/web/src/modules/`)
+
+---
+
+## Estrutura Padrão de um Módulo
+
+```
+apps/web/src/modules/{entity}/
+├── core/                              # Lógica core do módulo
+│   ├── module.config.ts               # Configuração do módulo
+│   │
+│   ├── item/                          # Tudo relacionado a UM item
+│   │   ├── index.ts                   # Exports principais
+│   │   ├── {entity}-url-builder.ts    # Builder de URLs
+│   │   ├── enrichMapper.ts            # Mapper para enriquecer dados
+│   │   │
+│   │   ├── schemas/                   # Schemas do item
+│   │   │   ├── index.ts               # Exports dos schemas
+│   │   │   ├── schema.ts              # Schema TypeScript (SSOT)
+│   │   │   ├── schema.generated.json  # Schema gerado da API
+│   │   │   ├── base-schema.json       # Schema base (campos)
+│   │   │   ├── display-layer-schema.json  # Overrides de UI
+│   │   │   └── computed-schema.json   # Campos computados
+│   │   │
+│   │   └── computed-fields/           # Campos computados runtime
+│   │       ├── index.ts
+│   │       ├── {entity}-url.ts        # Gerador de URL
+│   │       └── assembleComputedData.ts
+│   │
+│   ├── list/                          # Lógica de listagem (opcional)
+│   │   └── ...
+│   │
+│   ├── libs/                          # Bibliotecas específicas (opcional)
+│   │   └── ...
+│   │
+│   └── services/                      # Services do módulo
+│       └── {Entity}Service.ts
+│
+└── features/                          # Features/páginas
+    ├── item-display/                  # Página individual
+    │   └── page-display/
+    │       ├── components/
+    │       │   └── sections/
+    │       └── data/
+    │           └── fetch{Entity}SSR.ts
+    │
+    └── search-list/                   # Listagem com busca (opcional)
+        ├── components/
+        │   └── fields/
+        ├── config/
+        │   └── schema.ts
+        └── hooks/
+```
+
+---
+
+## Arquivos Obrigatórios
+
+### **Core Item**
+
+| Arquivo | Responsabilidade |
+|---------|------------------|
+| `core/item/index.ts` | Exporta enrichMapper, urlBuilder, schemas |
+| `core/item/{entity}-url-builder.ts` | Gera URLs para páginas da entidade |
+| `core/item/enrichMapper.ts` | Enriquece dados com schema + computed |
+
+### **Schemas**
+
+| Arquivo | Responsabilidade |
+|---------|------------------|
+| `core/item/schemas/index.ts` | Exporta todos os schemas |
+| `core/item/schemas/schema.ts` | Schema TypeScript principal |
+| `core/item/schemas/schema.generated.json` | Schema gerado pela API (build time) |
+
+### **Computed Fields**
+
+| Arquivo | Responsabilidade |
+|---------|------------------|
+| `core/item/computed-fields/index.ts` | Exporta funções de computed |
+| `core/item/computed-fields/{entity}-url.ts` | Gera URL do item |
+| `core/item/computed-fields/assembleComputedData.ts` | Monta objeto computed |
+
+---
+
+## 🔄 Fluxo de Dados
+
+```
+API Response (raw data)
+        │
+        ▼
+┌─────────────────────┐
+│   enrichMapper()    │ ← Combina: data + schema + computedData
+└─────────────────────┘
+        │
+        ▼
+┌─────────────────────┐
+│  assembleComputed() │ ← Gera campos runtime (URLs, etc)
+└─────────────────────┘
+        │
+        ▼
+┌─────────────────────┐
+│  EnrichMapperResult │ → { data, schema, computedData, computedSchema }
+└─────────────────────┘
+        │
+        ▼
+    Components
+```
+
+---
+
+## Exemplo: Broker Module
+
+### **core/item/index.ts**
+```typescript
+export { brokerEnrichMapper as enrichMapper } from "./enrichMapper";
+export { brokerURLBuilder } from "./broker-url-builder";
+export * from "./schemas";
+export * from "./computed-fields";
+```
+
+### **core/item/schemas/index.ts**
+```typescript
+export { brokerEntitySchema, getBrokerEntitySchema, type EntitySchema, type FieldSchema } from "./schema";
+export { default as baseSchema } from "./base-schema.json";
+export { default as displayLayerSchema } from "./display-layer-schema.json";
+export { default as computedSchema } from "./computed-schema.json";
+```
+
+### **core/item/schemas/schema.ts**
+```typescript
+import generatedSchema from "./schema.generated.json";
+
+export interface EntitySchema {
+  entity: string;
+  version: string;
+  fields: FieldSchema[];
+}
+
+export interface FieldSchema {
+  key: string;
+  type: string;
+  categories: string[];
+  ui: { label: string; description?: string };
+  audit: { origin: string };
+}
+
+export const brokerEntitySchema = generatedSchema as EntitySchema;
+
+export async function getBrokerEntitySchema(): Promise<EntitySchema> {
+  return brokerEntitySchema;
+}
+```
+
+### **core/item/computed-fields/assembleComputedData.ts**
+```typescript
+import { generateBrokerUrl } from "./broker-url";
+
+export function assembleComputedData(rawData: Record<string, any>): Record<string, any> {
+  return {
+    src: generateBrokerUrl(rawData),
+  };
+}
+```
+
+### **core/item/enrichMapper.ts**
+```typescript
+import { baseSchema, displayLayerSchema, computedSchema } from "./schemas";
+import { mergeArraysByKey } from "@/libs/horizon-utils/merge-arrays-by-key";
+import type { EnrichMapperResult, FieldMetadata } from "@/libs/domain-data-display-enricher/types";
+import { assembleComputedData } from "./computed-fields";
+
+const displaySchema = mergeArraysByKey(baseSchema.fields, displayLayerSchema as any, "key");
+
+export const brokerEnrichMapper = (rawData: Record<string, any>): EnrichMapperResult => {
+  return {
+    data: rawData,
+    schema: displaySchema as FieldMetadata[],
+    computedData: assembleComputedData(rawData),
+    computedSchema: computedSchema as FieldMetadata[],
+  };
+};
+```
+
+---
+
+## 🆚 Comparação: Property vs Broker
+
+| Aspecto | Property | Broker |
+|---------|----------|--------|
+| **Complexidade** | Alta | Baixa |
+| `core/item/schemas/` | | |
+| `core/item/computed-fields/` | | |
+| `core/libs/` | (7 módulos) | |
+| `core/list/` | | |
+| `features/search-list/` | (20+ componentes) | |
+| `features/item-display/` | | |
+
+**Use Property** como referência para módulos complexos com busca.
+**Use Broker** como template para módulos simples (página individual apenas).
+
+---
+
+## 🚫 Erros Comuns
+
+### Schemas fora de `core/item/`
+```
+# ERRADO
+broker/core/schemas/
+
+# CORRETO
+broker/core/item/schemas/
+```
+
+### Imports com caminho antigo
+```typescript
+// ERRADO
+import baseSchema from "@/modules/broker/core/schemas/base-schema.json";
+
+// CORRETO
+import { baseSchema } from "./schemas";
+```
+
+### Dependência de pacote npm não instalado
+```typescript
+// ERRADO (se broker-model não está no package.json)
+import type { EntitySchema } from "@horizon-domains/broker-model";
+
+// CORRETO (tipos locais)
+export interface EntitySchema { ... }
+```
+
+---
+
+## Referências
+
+- **API Module Pattern**: [MODULE_CREATION_PATTERN.md](./MODULE_CREATION_PATTERN.md)
+- **Search Engine API**: [SEARCH_ENGINE_API.md](./SEARCH_ENGINE_API.md)
+- **Property Module**: `/apps/web/src/modules/property/` (referência completa)
+- **Broker Module**: `/apps/web/src/modules/broker/` (referência simplificada)

package/knowledge/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!**