@horizon-framework/website-dev-docs 2.3.0

package/knowledge/CRMS_INTEGRACOES.md

@@ -0,0 +1,151 @@
+# CRMs e Integrações — Pacotes de Conversão
+
+> Referência sobre os pacotes de integração CRM disponíveis e como acessar suas documentações internas.
+
+---
+
+## CONCEITO
+
+Cada CRM suportado pelo Horizon tem um **pacote npm** dedicado em `@horizon-integrations/[crm]`. Esses pacotes são a ponte entre o CRM externo e o Horizon.
+
+O pacote NÃO é parte do site — é uma dependência npm. O site instala o pacote e usa seus exports.
+
+---
+
+## PACOTES DISPONÍVEIS
+
+| Pacote npm | CRM | Localização local |
+|---|---|---|
+| `@horizon-integrations/si9-crm` | SI9 Sistemas | `horizon-integrations/lista-crms/si9` |
+| `@horizon-integrations/jetimob-crm` | Jetimob | `horizon-integrations/lista-crms/jetimob` |
+| `@horizon-integrations/publisher-crm` | Publisher | `horizon-integrations/lista-crms/publisher` |
+| `@horizon-integrations/arbo-crm` | Arbo | `horizon-integrations/lista-crms/arbo` |
+
+---
+
+## O QUE CADA PACOTE EXPORTA
+
+| Export | Função |
+|---|---|
+| Schema Zod de validação | Valida dados convertidos antes do sync |
+| EntitySchema com source tracking | Schema da entidade com metadados de origem |
+| Conversor de dados | Função que transforma dados crus → formato Horizon |
+| `FICHA_TECNICA_INTEGRACAO.md` | **DOC PRINCIPAL** — campos, tipos SQL, badges, filtros, transformações |
+
+---
+
+## NORMALIZAÇÃO DOS CAMPOS EXTRAS
+
+Cada CRM tem campos que vão além dos 45 base do Horizon. O conversor normaliza esses campos excedentes seguindo regras padronizadas:
+
+| Regra | Exemplo CRM | Resultado Horizon |
+|---|---|---|
+| Ponto → underscore | `insurance.letter` | `insurance_letter` |
+| Hífen → underscore | `air-conditioner` | `air_conditioner` |
+| Objeto aninhado → prefixo | `features.room` | `features_room` |
+| Booleans agrupados → array TEXT[] | `features.shed=true, features.elevator=true` | `features: ["Galpão", "Elevador"]` (labels PT-BR) |
+| Tudo snake_case minúsculo | `SuperHighlight` | `super_highlight` |
+
+Os arrays de labels (features, security, recreation, rural) são traduzidos pra PT-BR pelo conversor usando mapas de labels internos.
+
+---
+
+## PRESET DE EXIBIÇÃO — OBRIGATÓRIO EM TODA FICHA_TECNICA
+
+Toda FICHA_TECNICA_INTEGRACAO.md **DEVE** ter uma seção "Preset de Exibição Recomendado" que define:
+
+1. **Card de listagem** — Quais campos viram tarja, badge, atributo com ícone
+2. **Página de detalhe — Ficha** — Como organizar as seções de atributos (principal, características, segurança, lazer, dimensões, rural, etc.)
+3. **Página de detalhe — Valores** — Como organizar a caixa de valores lateral por operação
+
+Este preset é **agnóstico de tecnologia** — não menciona framework, componente ou site específico. Apenas descreve a organização recomendada dos dados pra qualquer interface.
+
+O agente de configuração de dados lê este preset e o traduz pra configuração específica do site (fields-lists, PropertyInfoBlock, ValuesBox, etc.).
+
+---
+
+## FICHA TÉCNICA — O QUE CONTÉM
+
+A FICHA_TECNICA_INTEGRACAO.md de cada CRM é a **bíblia** da integração. Contém:
+
+1. **Campos base** (45 campos Horizon) — como cada campo do CRM mapeia pro Horizon
+2. **Campos extras** — campos específicos do CRM com tipos SQL recomendados
+3. **Situações do site** — quais campos viram badge, tarja, flag
+4. **Transformações recomendadas** — subtipo, valor_m2, etc.
+5. **Mapeamento de labels** — tradução de enums pra PT-BR
+6. **Filtros de busca sugeridos** — quais campos usar como filtro e de que tipo
+7. **FTS** — quais campos incluir no full-text search
+8. **Índices recomendados** — B-tree, GIN, GIST
+9. **Limitações do CRM** — o que a API NÃO fornece
+
+---
+
+## REGRA OBRIGATÓRIA
+
+**SEMPRE ler a FICHA_TECNICA_INTEGRACAO.md do CRM ANTES de qualquer configuração.**
+
+O agente deve:
+1. Localizar o pacote npm do CRM (local ou via `node_modules`)
+2. Ler a FICHA_TECNICA completamente
+3. Usar as informações dela pra configurar banco, API e frontend
+4. NÃO inventar campos — usar apenas o que está documentado na ficha
+
+---
+
+## COMO ACESSAR A FICHA TÉCNICA
+
+### Via pacote local (desenvolvimento)
+```
+[repo-horizon-integrations]/lista-crms/[crm]/FICHA_TECNICA_INTEGRACAO.md
+```
+
+### Via node_modules (projeto do site)
+```
+apps/api/node_modules/@horizon-integrations/[crm]/FICHA_TECNICA_INTEGRACAO.md
+```
+
+### Docs internas do pacote (quando existem)
+```
+[pacote]/docs/
+├── API_CAMPOS_PUBLICOS.md     → Campos da API mapeados
+├── LACUNAS_E_PENDENCIAS.md    → O que falta na integração
+├── PLANO_CONVERSOR.md         → Plano de desenvolvimento do conversor
+└── PROGRESSO.md               → Status de implementação
+```
+
+---
+
+## SCRIPTS DE DESENVOLVIMENTO
+
+Cada pacote CRM tem seus próprios scripts no `package.json`. Os comandos podem variar entre CRMs — **sempre consultar o `package.json` ou `README.md` do pacote específico** pra saber quais scripts existem e como usá-los.
+
+Todos os pacotes CRM provavelmente possuem funções para:
+- **Download** — Baixar dados da API do CRM
+- **Conversão** — Converter dados crus pro formato Horizon
+- **Profiling** — Analisar os dados crus e convertidos (distribuição de campos, valores únicos)
+- **Upload** — Enviar dados convertidos pra API do site
+
+Os nomes dos scripts e os detalhes de cada um variam por CRM.
+
+### Regras de upload
+
+- **Autenticação:** O endpoint de sync da API exige header de autenticação. O valor está no `.env` da API como `API_SECRET_KEY`.
+- **Batching obrigatório:** A API aceita no máximo ~50 itens por request (transação Prisma tem timeout de 5s). Enviar mais causa `Transaction already closed`.
+- **Script de upload do pacote pode não fazer batching** — se der timeout, enviar manualmente em lotes de 50.
+- **API precisa estar rodando** na porta configurada.
+- **Após upload:** Regenerar schema no frontend se houve mudança no pacote CRM.
+
+- **API precisa estar rodando** na porta configurada (geralmente 5000)
+- **Após upload:** Regenerar schema no frontend se houve mudança no pacote CRM
+
+---
+
+## CAMPOS CUSTOMIZADOS (fields[])
+
+Alguns CRMs (como SI9) têm campos customizados que o cliente cria livremente. Estes vêm como array JSONB `{field, value}`.
+
+O conversor pode ter **campos reconhecidos** — fields customizados que são mapeados automaticamente pra campos Horizon. Exemplo no SI9:
+- Campo custom "Corretor" → alimenta `corretor_nome`
+- Campo custom "Corretor ID" → alimenta `corretor_key`
+
+Os campos não reconhecidos são preservados no array `fields` pra exibição na página do imóvel.

package/knowledge/DESIGN_AVANCADO.md

@@ -0,0 +1,403 @@
+# Design Avancado — Estilo de Design Horizon (Estilo Jefferson)
+
+> Padroes visuais, composicoes, animacoes e estilo de design extraidos das paginas avancadas.
+> Este documento ensina COMO criar paginas e secoes que seguem o estilo Horizon.
+
+---
+
+## Assinatura Visual — 15 Padroes Recorrentes
+
+1. Hero com imagem 70% a direita + conteudo alinhado a esquerda
+2. Gradientes sutis (primary → primary-l1)
+3. Orbs decorativos (blur-3xl) em cantos/backgrounds
+4. Tipografia bold e clara (type-headline com gradiente)
+5. Alternancia background/surface entre secoes
+6. Cards com border + hover glow primary
+7. Carousels com autoplay 4000ms
+8. Spacing generoso (py-24, space-y-32)
+9. Icones em backgrounds arredondados (rounded-2xl + bg-primary/10)
+10. Somente 2 CTAs por section (primary + secondary)
+11. Imagens com overlay gradientes em camadas
+12. Stats com contadores animados (Intersection Observer)
+13. Badges/overlines com icone antes de headlines
+14. Testimonials com avatares e ratings
+15. Gallery em masonry com fade bottom
+
+---
+
+## HERO SECTIONS
+
+### Estrutura Base (padrao recorrente)
+
+```
+[Background Image 70% direita] → [Gradient Overlay camadas] → [Conteudo Esquerda]
+```
+
+### Camadas do Hero (de baixo pra cima)
+
+1. **Imagem** — posicionada com `left-[20%]`, ocupa ~70% da tela
+2. **Dark overlay** — `bg-background/40`
+3. **Gradiente lateral** — `linear-gradient(to right, black 20%, transparent 70%)`
+4. **Glow ball primary** — radial-gradient com blur-3xl, opacity-50
+
+```tsx
+{/* Camada 1: Imagem a direita */}
+<div className="absolute inset-0 left-[20%]">
+  <div className="w-full h-full bg-cover bg-center"
+       style={{backgroundImage: "url(...)"}} />
+</div>
+
+{/* Camada 2: Dark overlay */}
+<div className="absolute inset-0 bg-background/40" />
+
+{/* Camada 3: Gradiente lateral */}
+<div className="absolute inset-0"
+     style={{background: "linear-gradient(to right, black 20%, transparent 70%)"}} />
+
+{/* Camada 4: Glow ball */}
+<div className="absolute top-[-10%] left-[0%] w-[600px] h-[600px] rounded-full opacity-50 blur-3xl"
+     style={{background: "radial-gradient(circle, var(--primary) 0%, transparent 70%)"}} />
+```
+
+### Elementos do Hero (de cima pra baixo)
+
+1. **Overline/Badge** — pill com icone + texto
+2. **Headline (h1)** — 4xl mobile → 7xl desktop, linha 2 em gradiente primary
+3. **Body Copy** — text-lg, white/90%, max-w-2xl
+4. **2 CTAs** — primary + outline com backdrop-blur
+
+```tsx
+{/* Overline */}
+<div className="inline-flex items-center gap-2 px-4 py-2 rounded-full bg-primary/10">
+  <Icon className="size-4 text-primary" />
+  <span className="text-sm font-semibold">Label</span>
+</div>
+
+{/* Headline com gradiente */}
+<h1 className="type-headline leading-tight leading-trim text-4xl md:text-5xl lg:text-7xl font-bold">
+  Texto Normal
+  <span className="text-transparent bg-clip-text bg-linear-to-r from-primary to-primary-l1">
+    Texto em Gradiente
+  </span>
+</h1>
+
+{/* CTAs */}
+<Button size="lg" className="bg-primary hover:bg-primary/90">
+  Acao Principal
+</Button>
+<Button size="lg" variant="outline"
+        className="bg-white/10 backdrop-blur-sm text-white border-white/30">
+  Acao Secundaria
+</Button>
+```
+
+---
+
+## LAYERS FLUTUANTES (Orbs Decorativos)
+
+Padrao mais marcante do estilo. Orbs de cor com blur gigante que flutuam atras do conteudo.
+
+### Tipos de Layers
+
+**1. Glow Ball Primary (mais comum)**
+```tsx
+<div className="absolute top-20 left-10 w-96 h-96 bg-primary/5 rounded-full blur-3xl" />
+```
+
+**2. Glow Ball Secondary**
+```tsx
+<div className="absolute bottom-20 right-10 w-96 h-96 bg-secondary/5 rounded-full blur-3xl" />
+```
+
+**3. Radial Gradient (Hero)**
+```tsx
+<div className="absolute top-[-10%] left-[0%] w-[600px] h-[600px] rounded-full opacity-50 blur-3xl"
+     style={{background: "radial-gradient(circle, var(--primary) 0%, transparent 70%)"}} />
+```
+
+### Regras dos Orbs
+- SEMPRE `position: absolute` dentro de secao `relative overflow-hidden`
+- SEMPRE `blur-3xl` (nunca blur menor)
+- Opacidade: 5-15% para bg-primary/bg-secondary, 30-50% para radial-gradient
+- Tamanho: w-96 h-96 (padrao) ou w-[600px] h-[600px] (hero)
+- Posicao: cantos opostos da secao (top-left + bottom-right)
+- NUNCA mais que 2 orbs por secao
+
+---
+
+## BACKGROUNDS E TRANSICOES ENTRE SECOES
+
+### Paleta de Backgrounds
+
+```
+bg-background          → Cor base (escura em dark mode)
+bg-surface             → Ligeiramente mais clara
+bg-surface/30          → Surface com transparencia
+bg-card                → Fundo de card
+```
+
+### Padrao de Alternancia
+
+```
+Secao 1: bg-background
+Secao 2: bg-linear-to-br from-background via-surface/30 to-background
+Secao 3: bg-surface
+Secao 4: bg-background
+Secao 5: bg-linear-to-br from-surface/30 via-background to-surface/30
+```
+
+### Gradientes de Background
+
+```tsx
+{/* Diagonal suave */}
+className="bg-linear-to-br from-background via-surface/30 to-background"
+
+{/* Bottom fade */}
+className="bg-linear-to-b from-background to-surface"
+
+{/* Right fade */}
+className="bg-linear-to-r from-background to-surface/30"
+```
+
+---
+
+## TIPOGRAFIA
+
+### Classes Custom (SEMPRE usar)
+
+```
+type-headline  → Bold, leading-tight, leading-trim
+type-body      → Normal weight, leading-normal, leading-trim
+type-title     → Semibold, leading-tight
+type-overline  → Uppercase, tracking-wider, font-semibold
+type-button    → font-semibold, leading-trim
+type-display   → Muito grande, bold
+```
+
+### Escala Responsiva
+
+| Contexto | Mobile | Tablet | Desktop |
+|---|---|---|---|
+| h1 (Hero) | text-4xl | text-5xl | text-6xl a text-7xl |
+| h2 (Section Title) | text-3xl | text-4xl | text-5xl |
+| h3 (Card Title) | text-xl | text-2xl | text-2xl a text-3xl |
+| Body | text-base | text-lg | text-lg a text-xl |
+| Overline | text-xs | text-sm | text-sm |
+
+### Padrao de Headline com Gradiente
+
+```tsx
+<h2 className="type-headline leading-tight leading-trim text-3xl md:text-4xl lg:text-5xl">
+  Linha Normal de Texto
+  <span className="text-transparent bg-clip-text bg-linear-to-r from-primary to-primary-l1">
+    Texto Destacado em Gradiente
+  </span>
+</h2>
+```
+
+### Largura Maxima de Texto
+- Headlines: sem limite (mas ficam dentro de container)
+- Body/descricao: `max-w-2xl` ou `max-w-3xl` + `mx-auto` se centralizado
+
+---
+
+## COLORIMETRIA
+
+### Uso Proporcional
+
+- **Primary:** 70% (headlines, icones, botoes, acentos, gradientes)
+- **Secondary:** 20% (CTAs alternativas, highlights, variacao)
+- **Neutros:** 10% (borders, muted-foreground, separadores)
+
+### Cores Recorrentes
+
+```tsx
+// Textos
+text-primary                  // Destaque principal
+text-foreground               // Texto padrao
+text-muted-foreground         // Texto secundario
+text-white                    // Sobre fundos escuros
+
+// Backgrounds
+bg-primary/10                 // Fundo suave de icone/badge
+bg-surface                    // Fundo alternativo de secao
+bg-card                       // Fundo de card
+
+// Borders
+border-border                 // Borda padrao
+border-primary/50             // Borda hover
+
+// Sombras
+shadow-primary/10             // Sombra colorida no hover
+```
+
+### Gradientes de Texto
+```tsx
+// Gradiente primary (mais usado)
+className="text-transparent bg-clip-text bg-linear-to-r from-primary to-primary-l1"
+
+// Gradiente primary-secondary (raro)
+className="text-transparent bg-clip-text bg-linear-to-r from-primary to-secondary"
+```
+
+---
+
+## ESPACAMENTO PADRAO
+
+### Padding de Secoes
+```tsx
+className="py-16 md:py-20 lg:py-24"    // Padrao
+className="py-24 md:py-32"              // Secoes grandes (hero, CTA final)
+```
+
+### Gaps
+```
+Entre secoes: space-y-32 ou cada secao com seu py-24
+Entre elementos da secao: gap-12 a gap-20
+Cards em grid: gap-4 a gap-8
+Elementos dentro de card: gap-2 a gap-4
+```
+
+### Container
+```tsx
+<div className="container">  {/* max-width automatico + padding lateral */}
+```
+
+---
+
+## CARDS
+
+### Card Padrao (border + hover glow)
+
+```tsx
+<div className="p-6 rounded-2xl bg-card border border-border
+                hover:border-primary/50 hover:shadow-lg hover:shadow-primary/10
+                transition-all duration-300">
+  {/* Icone */}
+  <div className="inline-flex items-center justify-center size-16 rounded-2xl bg-primary/10">
+    <Icon className="size-8 text-primary" />
+  </div>
+  {/* Titulo */}
+  <h3 className="type-title text-lg font-bold mt-4">{title}</h3>
+  {/* Descricao */}
+  <p className="type-body text-sm text-muted-foreground mt-2">{description}</p>
+</div>
+```
+
+### Variacoes
+- **Com imagem top:** imagem acima, conteudo abaixo
+- **Com gradiente:** `bg-linear-to-br from-primary/5 to-transparent`
+- **Com quote icon:** icone de aspas flutuando no top-right
+- **Com badge:** status badge no canto
+
+---
+
+## ANIMACOES (Framer Motion)
+
+### Fade-in on Scroll (mais usado)
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  whileInView={{ opacity: 1, y: 0 }}
+  viewport={{ once: true }}
+  transition={{ duration: 0.6 }}
+>
+```
+
+### Stagger Children (items em sequencia)
+```tsx
+transition={{ duration: 0.6, delay: index * 0.1 }}
+```
+
+### Hover Scale (imagens e icones)
+```tsx
+className="group-hover:scale-105 transition-transform duration-500"
+```
+
+### Counter Animation (stats)
+```tsx
+// Intersection Observer detecta visibilidade
+// requestAnimationFrame anima de 0 ate o valor
+// Duracao: ~2000ms
+```
+
+### Carousel Autoplay
+```tsx
+plugins={[Autoplay({ delay: 4000, stopOnInteraction: true })]}
+```
+
+---
+
+## IMAGENS
+
+### Overlays em Camadas (padrao mais usado)
+```tsx
+{/* Bottom-to-top (para texto sobre imagem) */}
+<div className="absolute inset-0 bg-linear-to-t from-black/80 via-black/10 to-transparent" />
+
+{/* Hover reveal */}
+<div className="absolute inset-0 bg-black/0 group-hover:bg-black/40 transition-colors" />
+
+{/* Fade lateral (hero) */}
+<div style={{background: "linear-gradient(to right, var(--background) 0%, transparent 25%, transparent 75%, var(--background) 100%)"}} />
+```
+
+### Aspect Ratios
+- Hero: full-width, min-h-[90vh]
+- Features: aspect-[4/3]
+- Gallery: aspect-square
+- Video: aspect-video
+
+### Masonry Gallery
+```css
+column-count: 2;     /* mobile */
+column-gap: 12px;
+@media (min-width: 768px) { column-count: 3; }
+```
+
+---
+
+## ESTRUTURA PADRAO DE PAGINA
+
+### Pagina Simples (4-5 secoes)
+1. Hero Section
+2. Features/Benefits (carousel ou grid alternado)
+3. CTA Section
+4. (Opcional) Testimonials ou FAQ
+
+### Pagina Completa (10+ secoes, ex: Institucional)
+1. Hero
+2. About
+3. Stats (contadores animados)
+4. Video
+5. History
+6. Differentials (carousel 6 items)
+7. Gallery (masonry)
+8. Services (grid 4 colunas)
+9. Team (carousel autoplay)
+10. Awards
+11. Units
+12. Testimonials (carousel)
+13. CTA Final
+
+### Densidade de Conteudo
+- Pouco texto por secao (max-w-2xl a max-w-3xl)
+- Grande espacamento vertical (py-24, gap-12)
+- Hierarquia clara: Overline → Headline → Body → CTA
+- Whitespace como componente de design
+- Tamanho de imagens: 50% da tela, nunca 100% (exceto hero)
+
+---
+
+## FLUXO DE CRIACAO
+
+1. Definir objetivo e conteudo da pagina
+2. Desenhar wireframe (ASCII) com secoes
+3. Escolher secoes do catalogo (DESIGN_TEMPLATES_CATALOG.md)
+4. Compor a pagina combinando secoes
+5. Aplicar layers flutuantes (orbs decorativos)
+6. Aplicar gradientes entre secoes (alternancia background/surface)
+7. Adicionar animacoes (fade-in on scroll)
+8. Customizar textos, imagens, cores
+9. Testar responsividade (mobile, tablet, desktop)
+10. Rodar checklist do AGENTE_LAYOUT_DESIGNER (18 itens)