@horizon-framework/website-dev-docs 2.3.0

package/knowledge/SISTEMA_MODULAR.md

@@ -0,0 +1,109 @@
+# Sistema Modular — Como Funcionam Modulos no Horizon
+
+> Cada entidade de dados (imovel, corretor, condominio) e um modulo independente.
+
+---
+
+## Conceito
+
+Um modulo Horizon e uma unidade completa que cobre uma entidade de ponta a ponta:
+- Pacote NPM com schema base (dominio)
+- Banco de dados (tabela, indices, FTS)
+- API backend (controllers, services, schemas)
+- Frontend (core, features, customs)
+
+---
+
+## Modulos Existentes
+
+| Modulo | Backend | Frontend | NPM Domain | Status |
+|---|---|---|---|---|
+| **Property** (Imoveis) | Completo | Completo (10+ subprojetos) | @horizon-domains/property-model | Producao |
+| **Broker** (Corretores) | Completo | Completo (2 subprojetos) | @horizon-domains/broker-model | Producao |
+| **Institucional** | N/A | Parcial (so localizacao) | N/A | Parcial |
+| **Financiamento** | N/A | Parcial (componentes) | N/A | Parcial |
+
+### Modulos Futuros (pacotes criados mas vazios)
+- Blog
+- Cidade e Bairros
+- Condominio/Empreendimentos
+- Instagram Advanced
+
+---
+
+## Estrutura de um Modulo Completo
+
+### Backend (apps/api/src/modules/{entity}/)
+```
+modules/{entity}/
+├── schemas/
+│   ├── entity-schema.ts          # SSOT local (~1000 linhas)
+│   ├── entity-schema.zod.ts      # Validacao Zod
+│   └── search-schema.ts          # Schema de busca
+├── controllers/
+│   ├── search.controller.ts      # POST busca
+│   ├── find.controller.ts        # POST busca unica
+│   ├── sync.controller.ts        # PUT/DELETE sincronizacao
+│   └── schemas.controller.ts     # GET schemas
+├── services/
+│   ├── search.service.ts
+│   ├── find.service.ts
+│   └── sync.service.ts
+└── mappers/
+    ├── computedFields/           # Campos derivados
+    └── dataModifier/             # Regras de negocio
+```
+
+### Frontend (apps/web/src/modules/{entity}/)
+```
+modules/{entity}/
+├── core/
+│   ├── item/                     # Configuracao de 1 item
+│   │   ├── schemas/              # TypeScript + JSON schemas
+│   │   ├── computed-fields/      # Campos computados runtime
+│   │   ├── enrichMapper.ts       # Mapper de enriquecimento
+│   │   └── {entity}-url-builder.ts
+│   ├── list/                     # Configuracao de lista
+│   ├── services/                 # Servicos de API
+│   └── libs/                     # Libs especificas
+├── features/                     # Features/paginas
+│   ├── item-display/             # Pagina individual
+│   ├── search-list/              # Listagem com busca
+│   ├── favorites/                # Favoritos
+│   └── item-print/               # Impressao
+└── customs/                      # Componentes customizados
+    ├── home-search-bar/
+    └── {entity}-showcase/
+```
+
+---
+
+## Registro de Modulos
+
+O frontend tem um `MODULES_REGISTRY` que conecta modulos com:
+- Sitemap providers
+- Rotas dinamicas
+- Resolvers de dados
+
+---
+
+## Como Criar Modulo Novo
+
+Ver knowledge `MODULE_CREATION_PATTERN.md` para o passo-a-passo completo:
+1. Criar pacote NPM com schema base
+2. Criar tabela SQL + indices + FTS
+3. Criar modulo na API (schemas, controllers, services)
+4. Criar modulo no frontend (core, features)
+5. Registrar no MODULES_REGISTRY
+
+---
+
+## Integracao com CRM
+
+Modulos de entidade podem receber dados de CRMs externos:
+- Property ← Jetimob, SI9, Publisher, Arbo
+- Broker ← (futuro)
+- Condominio ← (futuro)
+
+Cada CRM tem um pacote conversor que transforma dados para o formato Horizon.
+Ver knowledge `CRMS_INTEGRACOES.md` e `SISTEMA_SCHEMAS.md`.

package/knowledge/SISTEMA_SCHEMAS.md

@@ -0,0 +1,126 @@
+# Sistema de Schemas — Domain Models e Conversores
+
+> Como schemas base, conversores CRM e entity-schema se conectam.
+
+---
+
+## Cadeia de Schemas
+
+```
+1. PACOTE DOMINIO BASE (@horizon-domains/{entity}-model)
+   → 45 campos base padronizados
+   → TypeScript + Zod
+   ↓
+2. PACOTE CONVERSOR CRM (@horizon-integrations/{crm}-crm)
+   → Converte formato CRM → formato Horizon
+   → Adiciona campos extras do CRM (80+ campos)
+   → Schema Zod de validacao
+   → FICHA_TECNICA_INTEGRACAO.md
+   ↓
+3. ENTITY-SCHEMA no Backend (apps/api/src/modules/{entity}/schemas/)
+   → Importa schema do pacote CRM
+   → Adiciona overrides locais
+   → Adiciona campos computed
+   → Adiciona campos customizados do cliente
+   → SSOT v2.0 (~1000 linhas)
+   ↓
+4. TABELA no Banco de Dados
+   → Colunas baseadas no entity-schema
+   → Indices, FTS tsvector, PostGIS geometry
+   ↓
+5. SCHEMA GERADO no Frontend
+   → npx tsx scripts/generate-schema.ts
+   → schema.generated.json
+   → Usado por enrichMapper, fields-lists, display
+```
+
+---
+
+## Pacote Dominio Base
+
+**Localização NPM:** `@horizon-domains/{entity}-model`
+**Repo:** `/root/github/horizon-npm-packages/horizon-modules/{entity}/domain-data/`
+
+### Property Domain (45 campos base)
+
+Campos que TODO imovel tem, independente do CRM:
+- Identificacao: reference, title, description
+- Comercial: operacao, valor_venda, valor_locacao, valor_diaria
+- Estrutura: area_total, dormitorios, banheiros, vagas_garagem, tipo, subtipo
+- Localizacao: endereco_cidade, endereco_bairro, lat, lng
+- Caracteristicas: caracteristicas[], tags[]
+- Midia: images[], videos[]
+- Sistema: created_at, updated_at
+
+### Outros Dominios
+- `@horizon-domains/broker-model` — Campos base de corretores
+- Blog, Condominio, etc. — Pacotes criados mas vazios
+
+---
+
+## Pacotes Conversores CRM
+
+**Localização NPM:** `@horizon-integrations/{crm}-crm`
+**Repo:** `/root/github/horizon-npm-packages/horizon-integrations/lista-crms/{crm}/`
+
+### CRMs Disponíveis
+
+| CRM | Pacote | Campos | Status |
+|---|---|---|---|
+| SI9 | @horizon-integrations/si9-crm | ~60 campos | Publicado |
+| Jetimob | @horizon-integrations/jetimob-crm | ~80 campos | Publicado |
+| Publisher | @horizon-integrations/publisher-crm | ~70 campos | Publicado |
+| Arbo | @horizon-integrations/arbo-crm | ~65 campos | Publicado |
+
+### O que cada pacote CRM exporta
+- `horizon-property-schema-by-{crm}.ts` — Schema com key, label, type, enum
+- `horizon-property-schema-by-{crm}.zod.ts` — Validacao Zod
+- `FICHA_TECNICA_INTEGRACAO.md` — Documentacao completa do CRM
+- Funcao de conversao: dados CRM → formato Horizon
+
+### Integration Toolkit
+**Pacote:** `@horizon-integrations/integration-toolkit`
+Base reutilizavel para criar novos conversores (batch converter, helpers).
+
+---
+
+## SSOT v2.0 (Entity Schema)
+
+Cada modulo no backend tem um entity-schema.ts que e o SSOT:
+
+```typescript
+{
+  key: "campo_exemplo",
+  type: "String",
+  categories: ["valores"],
+  enum: { "key": "Label" },
+  format: "currency",
+  unit: "BRL",
+  rules: { conditions: ["operacao:venda"] },
+  validation: { required: true, min: 0 },
+  ui: {
+    label: "Campo Exemplo",
+    searchable: true,
+    filterable: true,
+    sortable: true
+  },
+  audit: { origin: "horizon-base" }
+}
+```
+
+Ver knowledge `SSOT_SPECIFICATION_V2.md` para especificacao completa.
+
+---
+
+## Fluxo ao Trocar CRM
+
+1. Instalar novo pacote CRM no backend
+2. Atualizar imports no entity-schema.ts
+3. Recriar tabela no banco (DROP + CREATE baseado no novo schema)
+4. Gerar Prisma client
+5. Reiniciar API
+6. Re-sincronizar dados
+7. Regenerar schema no frontend
+8. Ajustar campos na busca, cards, pagina
+
+Ver checklist `TROCAR_CRM.md` para o passo-a-passo completo.

package/knowledge/SSOT_SPECIFICATION_V2.md

@@ -0,0 +1,333 @@
+# SSOT (Single Source of Truth) - Especificação v2.0
+
+## Visão Geral
+
+O novo formato SSOT v2.0 organiza metadados de campos em **contextos específicos**, permitindo separação clara de responsabilidades e melhor organização dos dados.
+
+### Filosofia do Formato
+- **Contextos Separados**: Cada tipo de metadado tem seu lugar específico
+- **Estrutura Hierárquica**: Agrupamento lógico das propriedades
+- **Flexibilidade**: Campos podem ser vazios e preenchidos conforme necessário
+- **Evolução Gradual**: Estrutura permite crescimento sem quebrar compatibilidade
+
+---
+
+## Estrutura dos Contextos
+
+### 1. **RAIZ** - Identificação Básica
+```typescript
+{
+  "key": "campo_exemplo",           // Identificador único (snake_case)
+  "type": "String",                 // Tipo de dado (String, Number, Boolean, String[], Json)
+  "enum": {"key": "Label"},         // Valores possíveis (quando aplicável)
+  "format": "currency",             // Formatação de exibição
+  "unit": "BRL",                    // Unidade de medida
+  "categories": ["valores"]         // Tags/categorias para filtros
+}
+```
+
+### 2. **RULES** - Regras e Relações
+```typescript
+"rules": {
+  "parent": "tipo",                 // Campo pai hierárquico
+  "conditions": ["operacao:venda"]  // Condições de visibilidade
+}
+```
+
+### 3. **VALIDATION** - Validação Backend/Zod
+```typescript
+"validation": {
+  "required": true,                 // Campo obrigatório
+  "min": 0,                        // Valor mínimo (números)
+  "max": 999999.99,                // Valor máximo (números)
+  "minLength": 3,                  // Tamanho mínimo (strings)
+  "maxLength": 200,                // Tamanho máximo (strings)
+  "precision": 2                   // Casas decimais
+}
+```
+
+### 4. **DB** - Configurações de Banco
+```typescript
+"db": {
+  // VAZIO por enquanto - será preenchido conforme necessário
+  // Futuro: index, unique, default, etc.
+}
+```
+
+### 5. **UI** - Interface e Experiência
+```typescript
+"ui": {
+  "label": "Campo Exemplo",        // Rótulo para exibição
+  "description": "Texto de ajuda", // Helper text para formulários
+  "placeholder": "Digite...",      // Placeholder para inputs
+  "icon": "home",                  // Ícone semântico
+  "displayTemplate": "{{value}} m²", // Template de exibição
+  "mask": "cpf",                   // Máscara de input (cpf, cnpj, cep, phone, email)
+  "searchable": true,              // Pesquisável por texto
+  "filterable": true,              // Aparece nos filtros
+  "sortable": true                 // Permite ordenação
+}
+```
+
+### 6. **AUDIT** - Auditoria e Rastreamento
+```typescript
+"audit": {
+  "origin": "horizon-base/imovel", // Origem do campo
+  "modifiedBy": ["system"]         // Histórico de modificações
+}
+```
+
+---
+
+## Tipos de Dados Suportados
+
+| Tipo | Descrição | Exemplo |
+|------|-----------|---------|
+| `String` | Texto simples | "Casa no Centro" |
+| `Number` | Números inteiros e decimais | 150000.50 |
+| `Boolean` | Verdadeiro/Falso | true, false |
+| `String[]` | Array de strings | ["piscina", "churrasqueira"] |
+| `Json` | Objeto JSON | {"lat": -27.5, "lng": -48.5} |
+| `Json[]` | Array de objetos | [{"url": "...", "caption": "..."}] |
+
+---
+
+## Formatos de Exibição
+
+| Format | Unit | Exemplo Entrada | Exemplo Saída |
+|--------|------|----------------|---------------|
+| `currency` | `BRL` | 150000 | R$ 150.000,00 |
+| `currency` | `USD` | 150000 | $ 150,000.00 |
+| `area` | `m2` | 150 | 150 m² |
+| `distance` | `km` | 1.5 | 1,5 km |
+| `percent` | - | 0.15 | 15% |
+| `count` | - | 3 | 3 itens |
+| `date` | - | "2024-01-01" | 01/01/2024 |
+| `datetime` | - | "2024-01-01T10:30:00Z" | 01/01/2024 10:30 |
+
+---
+
+## Categorias Recomendadas
+
+| Categoria | Descrição | Campos Típicos |
+|-----------|-----------|----------------|
+| `valores` | Campos monetários | valor_venda, valor_locacao |
+| `localizacao` | Endereço e geolocalização | endereco_cidade, latitude, longitude |
+| `estrutura` | Características físicas | quartos, banheiros, area_total |
+| `identificacao` | Títulos e referências | title, reference |
+| `comercial` | Informações comerciais | operacao, status |
+| `caracteristicas` | Amenidades e comodidades | piscina, churrasqueira |
+| `sistema` | Campos internos | id, created_at, updated_at |
+
+---
+
+## Máscaras Disponíveis
+
+### Automáticas (inferidas do format + unit)
+- `currency-brl` → R$ 1.000,00 (format: currency + unit: BRL)
+- `currency-usd` → $ 1,000.00 (format: currency + unit: USD)
+- `area` → 100 m² (format: area + unit: m2)
+- `distance` → 1,5 km (format: distance + unit: km)
+- `percent` → 15% (format: percent)
+- `date` → DD/MM/AAAA (format: date)
+
+### Explícitas (para casos específicos)
+- `cpf` → 000.000.000-00
+- `cnpj` → 00.000.000/0000-00
+- `cep` → 00000-000
+- `phone` → (00) 00000-0000
+- `email` → Validação de email
+
+---
+
+## Condições de Visibilidade
+
+### Operadores Disponíveis
+
+| Operador | Descrição | Exemplo |
+|----------|-----------|---------|
+| `:` (padrão) | Contém | `"operacao:venda"` |
+| `.equals` | Igual a | `"tipo.equals:apartamento"` |
+| `.not` | Diferente de | `"status.not:vendido"` |
+| `.in` | Está na lista | `"tipo.in:casa,apartamento"` |
+| `.gt` | Maior que | `"valor.gt:100000"` |
+| `.gte` | Maior ou igual | `"valor.gte:100000"` |
+| `.lt` | Menor que | `"quartos.lt:5"` |
+| `.lte` | Menor ou igual | `"area.lte:200"` |
+| `.exists` | Campo preenchido | `"condominio.exists:true"` |
+
+### Exemplos de Uso
+```typescript
+"rules": {
+  "conditions": [
+    "operacao:venda",              // operacao contém "venda"
+    "tipo.equals:apartamento",     // tipo é exatamente "apartamento"
+    "valor.gte:100000",            // valor >= 100000
+    "quartos.in:2,3,4"             // quartos é 2, 3 ou 4
+  ]
+}
+```
+
+---
+
+## Exemplos Práticos
+
+### Campo Simples
+```json
+{
+  "key": "title",
+  "type": "String",
+  "categories": ["identificacao"],
+  "validation": {
+    "required": true,
+    "minLength": 3,
+    "maxLength": 200
+  },
+  "ui": {
+    "label": "Título",
+    "description": "Título do imóvel",
+    "placeholder": "Ex: Casa no Centro",
+    "searchable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo com Enum
+```json
+{
+  "key": "tipo",
+  "type": "String",
+  "enum": {
+    "casa": "Casa",
+    "apartamento": "Apartamento",
+    "terreno": "Terreno"
+  },
+  "categories": ["estrutura"],
+  "validation": {
+    "required": true
+  },
+  "ui": {
+    "label": "Tipo",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo Monetário
+```json
+{
+  "key": "valor_venda",
+  "type": "Number",
+  "format": "currency",
+  "unit": "BRL",
+  "categories": ["valores"],
+  "validation": {
+    "min": 0,
+    "max": 999999999.99,
+    "precision": 2
+  },
+  "ui": {
+    "label": "Valor de Venda",
+    "displayTemplate": "{{value}}",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+### Campo com Condição
+```json
+{
+  "key": "valor_locacao",
+  "type": "Number",
+  "format": "currency",
+  "unit": "BRL",
+  "categories": ["valores"],
+  "rules": {
+    "conditions": ["operacao:locacao"]
+  },
+  "validation": {
+    "min": 0,
+    "precision": 2
+  },
+  "ui": {
+    "label": "Valor de Locação",
+    "filterable": true,
+    "sortable": true
+  },
+  "audit": {
+    "origin": "horizon-base/imovel"
+  }
+}
+```
+
+---
+
+## Geração Automática
+
+### Zod Schema
+A partir do SSOT, é gerado automaticamente:
+- Schema Zod para validação
+- Tipos TypeScript inferidos
+- Funções de validação (parse, safeParse, partial)
+
+### Exemplo de Geração
+```typescript
+// Gerado automaticamente a partir do SSOT
+export const ImovelZod = z.object({
+  id: z.number().optional(),
+  reference: z.string().min(1).max(50),
+  title: z.string().min(3).max(200),
+  tipo: z.enum(["casa", "apartamento", "terreno"]),
+  valor_venda: z.number().min(0).multipleOf(0.01).optional()
+})
+
+export type ImovelType = z.infer<typeof ImovelZod>
+```
+
+---
+
+## Vantagens do Novo Formato
+
+1. **Organização Clara**: Cada contexto tem seu espaço definido
+2. **Flexibilidade**: Campos podem ser vazios e evoluir gradualmente  
+3. **Separação de Responsabilidades**: UI, validação, DB em contextos isolados
+4. **Manutenibilidade**: Fácil identificar onde cada metadado pertence
+5. **Evolução**: Adicionar novos contextos sem quebrar existentes
+6. **Reuso**: Mesmo campo pode ter comportamentos diferentes por contexto
+
+---
+
+## Checklist de Criação
+
+### Campo Mínimo Obrigatório
+- [ ] `key` - Identificador único
+- [ ] `type` - Tipo de dado  
+- [ ] `ui.label` - Rótulo para exibição
+- [ ] `audit.origin` - Origem do campo
+
+### Campo Típico (recomendado)
+- [ ] Validação básica (`required`, limites)
+- [ ] Categoria para organização
+- [ ] Formatação quando aplicável
+- [ ] Configurações de UI (searchable, filterable)
+
+### Campo Complexo
+- [ ] Enum quando valores limitados
+- [ ] Condições de visibilidade
+- [ ] Display template customizado
+- [ ] Relacionamentos hierárquicos
+
+---
+
+Esta especificação serve como **base definitiva** para criação de schemas SSOT v2.0 no sistema, garantindo consistência, flexibilidade e evolução controlada dos metadados.

package/knowledge/UI_KIT_COMPLETO.md

@@ -0,0 +1,125 @@
+# UI Kit Completo — Componentes do Horizon Web
+
+> shadcn/ui + componentes custom Horizon + componentes globais
+
+---
+
+## shadcn/ui Base (49 componentes)
+
+Componentes padrao do shadcn instalados em `src/components/ui/`:
+
+accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button, calendar, card, carousel, checkbox, collapsible, command, context-menu, dialog, drawer, dropdown-menu, form, hover-card, input, input-otp, label, menubar, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, sheet, sidebar, skeleton, slider, switch, table, tabs, textarea, toggle, toggle-group, tooltip
+
+---
+
+## Componentes Custom Horizon (src/components/ui/horizon-ui/)
+
+### Filtros e Pickers
+
+**HistogramRangeSlider** — Range slider com barras de histograma
+- Props: `buckets[], value, onChangeEnd, onClear, formatLabel, totalCount, isActive`
+- Dual slider com tooltip mostrando contagem por faixa
+- Usado na busca de imoveis para filtro de preco/area
+
+**HistogramRangeSelect** — Popover com histograma interativo
+- Props: `buckets[], value, onChangeEnd, onClear, formatLabel, placeholder, rangeHint`
+- Popover + histograma + exibicao de range selecionado
+
+**MultiSelect** — Select multiplo customizado
+- Selecao multipla com chips/tags
+
+**NumberSelector** — Seletor numerico
+- Incremento/decremento com botoes
+
+**Select** — Select customizado Horizon
+- Estilizacao e comportamento alem do shadcn base
+
+### Carousel e Animacao
+
+**Dots** — Indicador de slides (carousel)
+- Usado com Embla Carousel + useCarouselController
+
+**FadeSlider** — Slider com efeito fade
+- Transicao suave entre slides
+
+**TabsFloating** — Tabs flutuante
+- Tabs que flutua sobre o conteudo
+
+### Tipografia e Display
+
+**Overline** — Texto overline estilizado
+- Tipografia decorativa acima de titulos
+
+**VideoPlayerModal** — Modal para player de video
+- Modal fullscreen para reproducao de video
+
+---
+
+## Componentes Globais (src/components/global/)
+
+| Componente | O que faz |
+|---|---|
+| `FormAlertModal` | Modal de alerta para formularios (sucesso/erro) |
+| `GlobalLoading` | Loading global animado |
+| `PageLoading` | Loading especifico de pagina |
+| `ProseTypography` | Tipografia Prose avancada para conteudo longo |
+| `SplashScreen` | Tela de splash ao carregar |
+| `ExitIntentDialog` | Dialog quando usuario tenta sair |
+
+---
+
+## Outros Componentes
+
+| Componente | Pasta | O que faz |
+|---|---|---|
+| `WhatsAppFloatButton` | `components/whatsapp-float-button/` | Botao flutuante de WhatsApp |
+| `CookieConsent` | `components/` | Banner de consentimento de cookies |
+| `Confetti` | `components/ui/` | Efeito de confete (canvas-confetti) |
+| `Sonner` | `components/ui/` | Toast notifications (wrapper) |
+| `ThemeToggle` | `components/ui/` | Botao toggle tema light/dark |
+| `Logo` | `components/ui/` | Logo do projeto |
+| `NavigationLoadingOverlay` | `components/navigation/` | Overlay de loading na navegacao |
+| `FacebookWidget` | `components/widgets/` | Widget do Facebook |
+| `DebugJsonViewer` | `components/` | Viewer de JSON para debug |
+
+---
+
+## Icons
+
+**Pasta:** `components/ui/icons/`
+- `icon.tsx` — Componente wrapper de icone
+- `icon-registry.ts` — Registry centralizado de icones
+
+Icones sao referenciados por STRING (ex: "house", "phone"), nunca por import direto.
+
+---
+
+## Design System (src/design/)
+
+### Cards Decorativos
+- `CardIconTop` — Card com icone no topo
+- `CardStat` — Card de estatistica
+- `CardTestimonialPhoto` — Card de depoimento com foto
+
+### Creative Components
+- 5 Frame Decoratives (molduras decorativas)
+- 2 Person Frame Decoratives (molduras para fotos de pessoas)
+- 10 Randomized Compositions (composicoes aleatorias)
+
+### Assets
+- Frames, filters, shapes, patterns, grids (11 categorias)
+
+---
+
+## Storybook
+
+**Total:** 293 arquivos .stories espalhados pelo projeto
+**Comando:** `cd apps/web && pnpm storybook` (porta 6006)
+
+Distribuicao:
+- `/components/ui/` — ~49 stories (shadcn)
+- `/components/ui/horizon-ui/` — ~5 stories (custom)
+- `/components/global/` — ~5 stories
+- `/hooks/` — ~7 stories
+- `/design/general/creative/` — ~25+ stories
+- Restante em modulos (property, etc.)