@horizon-framework/website-dev-docs 2.3.0

package/knowledge/NAVEGACAO_DINAMICA.md

@@ -0,0 +1,233 @@
+# Navegacao Dinamica -- Sistema de Menus do Horizon
+
+> Arquitetura do sistema de navegacao: dados estaticos, fetchers dinamicos, composicao em camadas, provider pattern.
+
+**Localizacao:** `apps/web/src/capabilities/navigations/`
+
+---
+
+## Conceito
+
+O sistema de navegacao do Horizon usa **composicao em camadas**:
+
+```
+Building Blocks (Imoveis, QuemSomos, Anuncie...)
+    |  composicao simples
+Menus Compostos (Institucional = [QuemSomos, Localizacao, ...])
+    |  reutilizacao de blocos
+Menus Dinamicos (Venda, Locacao com children da API + contagem)
+    |  spread operator
+Menus Finais (headerMenu, footerMenu, drawerMenu)
+```
+
+Dados sao "burros" (so dados), componentes sao "inteligentes" (resolvem icones, estado ativo, etc.).
+
+---
+
+## Arquivos
+
+| Arquivo | Funcao |
+|---|---|
+| `types.ts` | Interface NavigationItem (title, href, icon, children, count, badge, etc.) |
+| `data/navigations.tsx` | Blocos basicos + menus compostos + `getMenus()` async |
+| `fetchers/property.ts` | Busca facets da API e gera children dinamicos (Venda/Locacao por tipo) |
+| `navigation.service.ts` | Cache server-side (`unstable_cache`, revalidate 1800s) |
+| `NavigationProvider.tsx` | Context client-side (`useNavigation()` hook) |
+| `helpers/` | `linkAttrs()`, `isActive()`, `slugify()`, `pluralize()` |
+
+---
+
+## Fluxo Completo
+
+```
+1. Server-side: layout.tsx chama await getNavigation()
+2. navigation.service.ts:
+   - DEV: chama getMenus() direto (sem cache)
+   - PROD: unstable_cache com revalidate: 1800s (30 min)
+3. getMenus() chama fetchers em paralelo (Promise.all)
+   - getVendaMenu() -> facet tipo_gen filtrado por operacao=venda
+   - getLocacaoMenu() -> facet tipo_gen filtrado por operacao=locacao
+4. Fetchers usam propertyService.search() com facets.includeCount=true
+5. API retorna facets com value + count por tipo de imovel
+6. Children montados com titulo, href (slug), count
+7. Resultado passa pelo NavigationProvider
+8. Client-side: useNavigation() retorna { headerMenu, footerMenu, drawerMenu }
+```
+
+---
+
+## Interface NavigationItem
+
+```typescript
+interface NavigationItem {
+  // Obrigatorios
+  title: string;          // "Venda", "Apartamentos"
+  href: string;           // "/imoveis?operacao=venda"
+
+  // Estrutura
+  children?: NavigationItem[];        // Submenu recursivo
+  separator?: boolean;                // Divisor visual
+
+  // Apresentacao
+  icon?: string;                      // Nome do icone (string, nao import)
+  thumbnail?: string;                 // URL de imagem (para cards)
+  overline?: string;                  // Texto acima
+  description?: string;               // Descricao/tooltip
+  badge?: string;                     // Text badge ("Novo", "3")
+
+  // Funcionalidade
+  count?: number;                     // Contagem dinamica (ex: 42 imoveis)
+  disabled?: boolean;
+  target?: "_self" | "_blank";
+  rel?: string;                       // Auto "noopener noreferrer" se _blank
+  match?: "exact" | "startsWith" | RegExp | ((pathname: string) => boolean);
+
+  // Avancado
+  id?: string;
+  audience?: ("guest" | "user" | "admin")[];
+  dropdownLayout?: 'default' | 'cards';  // Layout do dropdown (cards=4 cols com imagens)
+  meta?: Record<string, any>;
+}
+```
+
+---
+
+## Dinamico vs Estatico
+
+### Estaticos (em `data/navigations.tsx`)
+
+```typescript
+// Building blocks reutilizaveis
+export const Imoveis = { title: "Venda", href: "/imoveis?operacao=venda", icon: "property" };
+export const Especiais = { title: "Servicos", href: "#", dropdownLayout: "cards", children: [...] };
+
+// Fallback
+export const headerMainMenu: NavigationItem[] = [Imoveis, Locacao, Especiais, Institucional];
+```
+
+### Dinamicos (via `fetchers/property.ts`)
+
+```typescript
+// getVendaMenu() busca facets da API:
+{
+  title: "Venda",
+  href: "/imoveis?operacao=venda",
+  icon: "house",
+  children: [
+    { title: "Apartamentos", href: "/imoveis/venda/apartamentos?...", count: 1240 },
+    { title: "Casas", href: "/imoveis/venda/casas?...", count: 892 },
+    // ... gerado automaticamente pelos facets
+  ]
+}
+```
+
+---
+
+## Contagem Dinamica (count)
+
+```
+propertyService.search({
+  filters: { operacao: "venda" },
+  list: { limit: 1 },
+  facets: { includeCount: true, fields: [{ type: "terms", field: "tipo_gen" }] }
+})
+  -> API retorna: { facets: { data: { tipo_gen: [{ value: "Apartamento", count: 1240 }, ...] } } }
+  -> Mapped para NavigationItem com count
+  -> Renderizado: <span>{child.count}</span>
+```
+
+Os menus dinamicos se adaptam automaticamente ao trocar de CRM (dados vem da API via facets).
+
+---
+
+## Menus Finais
+
+| Menu | Composicao |
+|---|---|
+| `headerMenu` | [Venda(dinamico), Locacao(dinamico), Especiais(estatico), Institucional(estatico)] |
+| `footerMenu` | [Venda, Locacao, ...Especiais.children, ...Institucional.children] (flat) |
+| `drawerMenu` | [Venda, Locacao, ...Institucional.children, Especiais] (mobile) |
+
+---
+
+## Converters: Social e Contact -> NavigationItem
+
+O sistema converte dados de contato e redes sociais para NavigationItem, reutilizando a mesma interface:
+
+```typescript
+// Social -> NavigationItem
+toNavigationItem(social): { title: social.label, href: social.url, icon: getIconForSocial(social), target: "_blank" }
+
+// Contact -> NavigationItem
+toNavigationItem(contact): { title: contact.label, href: getContactUrl(contact), icon: getIconForContact(contact) }
+```
+
+**Registries:**
+- `capabilities/social/registry.ts` -- plataformas (instagram, facebook, whatsapp, etc.)
+- `capabilities/contacts/registry.ts` -- tipos de contato (whatsapp, telegram, mobile, email)
+
+**Dados:**
+- `capabilities/social/data/examples.ts` -- redes sociais do cliente
+- `capabilities/contacts/data/contacts.data.ts` -- contatos do cliente
+
+---
+
+## Helpers
+
+| Helper | Funcao |
+|---|---|
+| `isActive(pathname, item)` | Determina se item esta ativo (exact, startsWith, RegExp, funcao) |
+| `linkAttrs(item)` | Gera target/rel seguro (auto noopener noreferrer se _blank) |
+| `slugify(text)` | Gera URL amigavel ("Ponto Comercial" -> "ponto-comercial") |
+| `pluralize(word)` | Pluraliza em portugues ("Casa" -> "Casas", "Rural" -> "Rurais") |
+| `filterByAudience(items, role)` | Filtra por tipo de usuario |
+| `countBadges(items)` | Soma badges numericas recursivamente |
+
+---
+
+## Cache e Revalidacao
+
+```typescript
+// navigation.service.ts
+const getCachedNavigation = unstable_cache(
+  async () => getMenus(),
+  ["dynamic-navigation"],
+  { revalidate: 1800 }  // 30 minutos
+);
+
+// DEV: sem cache (reflete mudancas instantaneamente)
+// PROD: cache de 30min (economia de requests a API)
+```
+
+---
+
+## Componentes que Usam
+
+| Componente | Menu | Contexto |
+|---|---|---|
+| `NavigationDesktop.tsx` | headerMenu | Desktop dropdown com hover |
+| `NavigationDesktopDropdown.tsx` | headerMenu | Alternativa com HoverCard 3 colunas |
+| `FooterNavigation.tsx` | footerMenu | Links simples no rodape |
+| `MobileMenu.tsx` | drawerMenu | Menu recursivo em drawer |
+| `ContactBox.tsx` | contacts->nav | Contatos via converter |
+| `SocialLinks.tsx` | socials->nav | Redes sociais via converter |
+
+---
+
+## Como Trocar/Adicionar Menus
+
+1. **Bloco basico novo:** adicionar export const em `data/navigations.tsx`
+2. **Novo fetcher dinamico:** criar funcao em `fetchers/` usando fetchFacetMenu pattern
+3. **Menu composto:** compor com children usando blocos existentes
+4. **Menu final:** incluir nos arrays de headerMenu/footerMenu/drawerMenu em getMenus()
+5. **Cache:** revalida a cada 30min em prod; sem cache em dev
+
+---
+
+## Regras
+
+1. Icones sao STRINGS (ex: "house"), nunca imports diretos de Lucide
+2. NavigationItem e a interface unica para TODOS os contextos (header, footer, drawer, contatos, sociais)
+3. Menus dinamicos se adaptam automaticamente ao trocar de CRM (dados vem da API)
+4. Sempre usar `linkAttrs()` para gerar target/rel seguro
+5. Ao adicionar menu dinamico, seguir o pattern de `getVendaMenu()` como referencia

package/knowledge/PAGINAS_BASICAS.md

@@ -0,0 +1,63 @@
+# Paginas Basicas — Pacote Padrao Horizon
+
+> Todo site Horizon vem com ~14 paginas basicas incluidas no pacote.
+
+---
+
+## Lista Completa das Paginas Basicas
+
+| # | Rota | Pagina | Tipo |
+|---|---|---|---|
+| 1 | `/` ou `/home` | Home Page | Marketing |
+| 2 | `/imoveis/[[...slug]]` | Busca/Lista de Imoveis | SSR Dinamica |
+| 3 | `/imovel/[...slug]` | Detalhe do Imovel | SSR Dinamica |
+| 4 | `/corretor/[...slug]` | Perfil do Corretor | SSR Dinamica |
+| 5 | `/favoritos` | Favoritos | SSR |
+| 6 | `/imoveis-compartilhados/[[...slug]]` | Imoveis Compartilhados | SSR Dinamica |
+| 7 | `/quem-somos` | Quem Somos | Estatica |
+| 8 | `/localizacao` | Localizacao/Unidades | Estatica |
+| 9 | `/contato` | Formulario de Contato | Estatica |
+| 10 | `/financiamento` | Financiamento | Estatica |
+| 11 | `/anuncie-seu-imovel` | Anuncie | Estatica |
+| 12 | `/encomende-seu-imovel` | Encomende | Estatica |
+| 13 | `/obrigado` | Pagina de Agradecimento | Estatica |
+| 14 | `/termos-uso` | Termos de Uso | Legal |
+| 15 | `/politica-privacidade` | Politica de Privacidade | Legal |
+
+---
+
+## Paginas Auxiliares (incluso)
+
+| Rota | Pagina | Tipo |
+|---|---|---|
+| `/guia-de-compra` | Guia de Compra | Marketing |
+| `/guia-de-locacao` | Guia de Locacao | Marketing |
+| `/avaliacao-imovel` | Avaliacao de Imovel | Marketing |
+| `/login` | Login Admin | Minimal layout |
+| `/print-imovel/[reference]` | Impressao de Imovel | Print layout |
+| `/imovel/inspect/[...slug]` | Inspect Mode (admin) | Debug |
+| `/sitemap.xml` | Sitemap XML | SEO |
+
+---
+
+## Layouts
+
+As paginas sao organizadas em grupos de layout:
+
+- **(marketing)** — Layout completo com header, footer, navegacao
+- **(print)** — Layout minimo para impressao
+- **(minimal)** — Layout minimo (login)
+- **(design)** — Layout para paginas avancadas/demo
+
+---
+
+## Ao Criar Site Novo
+
+Todas as paginas basicas vem do template Horizon. O que trocar:
+1. **Home** — Trocar conteudo, imagens, textos
+2. **Quem Somos** — Trocar historia, fotos, missao/visao
+3. **Localizacao** — Trocar enderecos e mapa
+4. **Contato** — Trocar destino de leads
+5. **Financiamento** — Verificar bancos disponiveis
+6. **Termos/Privacidade** — Trocar nome da empresa
+7. **SEO** — Trocar meta tags em cada pagina