@horizon-framework/website-dev-docs 2.3.0

package/modules/property/MODULO_IMOBILIARIO.md

@@ -0,0 +1,356 @@
+# Módulo Imobiliário — Arquitetura Completa
+
+> Tudo sobre o módulo de imóveis: backend (API), frontend, listas de atributos, cards, página.
+> Genérico para qualquer CRM. Campos específicos vêm da FICHA_TECNICA de cada CRM.
+
+---
+
+## BACKEND (apps/api)
+
+### Estrutura do módulo
+```
+apps/api/src/modules/property/
+├── controllers/          → search, sync, batch-search, schemas
+├── services/             → search.service, sync.service, batch-search.service
+├── schemas/
+│   ├── source-schema.zod.ts    → Validação Zod (import do pacote CRM)
+│   └── entity-schema.ts        → Schema SSOT com display overrides e relações
+├── mappers/
+│   ├── dataModifier/rules.ts   → Transformações Etapa 3 (subtipo, etc.)
+│   └── computedFields/index.ts → Campos calculados (slug, thumbnails, endereço, flags)
+└── database/
+    └── tables/property/
+        ├── create.sql              → Schema do banco (seções: system, base, CRM extras, computed)
+        └── generated-columns.sql   → FTS vector + geom
+```
+
+### Arquivos que MUDAM ao trocar de CRM
+1. `package.json` — trocar pacote `@horizon-integrations/[crm]`
+2. `create.sql` — remover colunas do CRM antigo, adicionar do novo
+3. `generated-columns.sql` — atualizar FTS com campos do novo CRM
+4. `source-schema.zod.ts` — trocar import do Zod
+5. `entity-schema.ts` — trocar import do schema, bump version
+6. `rules.ts` — limpar regras do CRM antigo
+7. `computedFields/index.ts` — limpar computed do cliente, manter base
+
+### Endpoints principais
+- `POST /api/property/search` — Busca multipart (filters, facets, fts, geom, list, map)
+- `POST /api/property/batch-search` — Múltiplas buscas em 1 request
+- `PUT /api/property/sync` — Sincronização de dados (batches de 50 max)
+- `GET /api/property/schemas/entity` — Schema SSOT
+
+---
+
+## FRONTEND (apps/web)
+
+### Estrutura do módulo
+```
+apps/web/src/modules/property/
+├── core/                → Fundação reutilizável
+│   ├── services/PropertyService.ts  → Singleton com search, batchSearch, find, getDistinct
+│   ├── item/
+│   │   ├── page-config/             → ★ CONTRATOS + RESOLVERS (configuração central)
+│   │   │   ├── types.ts             → Todas as interfaces de contrato (16 sub-features)
+│   │   │   ├── resolve-contracts.ts → Função master: resolvePageContracts()
+│   │   │   └── resolvers/           → 1 resolver por sub-feature
+│   │   ├── fields-lists.ts          → TODAS as listas de campos (cards + página)
+│   │   ├── select-fields.config.ts  → Config de select por contexto (full, cardList, mapList)
+│   │   ├── schemas/schema.generated.json  → Schema gerado da API
+│   │   └── computed-fields/         → Campos computados no frontend
+│   └── libs/                        → Engines (enricher, URL parser, facets generator)
+├── features/
+│   ├── search-list/     → Buscador avançado + listagem
+│   ├── item-display/    → ★ Cards + página do imóvel (Feature-Based Provider Composition)
+│   │   ├── ui/          → Componentes de UI de field compartilhados
+│   │   ├── cards/       → Cards de listagem
+│   │   └── page-display/→ Página do imóvel com 16 sub-features
+│   │       └── sub-features/  → Cada sub-feature com provider + componentes
+│   ├── item-print/      → Página de impressão (reutiliza contratos sem providers)
+│   ├── item-inspect/    → Ferramenta de debug
+│   └── favorites/       → Favoritos
+└── customs/             → Vitrines, search bar da home
+```
+
+> **Arquitetura detalhada da página do imóvel:** ver [ITEM-DISPLAY-ARCHITECTURE.md](../../projects/ITEM-DISPLAY-ARCHITECTURE.md)
+
+---
+
+## 6 CATEGORIAS DE ATRIBUTOS ESPECIAIS
+
+Cada CRM traz dados diferentes, mas todos os atributos de layout caem em 6 categorias:
+
+| Cat. | Nome | Efeito | Onde aparece |
+|---|---|---|---|
+| **A** | Status do imóvel | Tarja diagonal, ticker banner, muda estado da página inteira | Card (tarja) + Página (banner) |
+| **B** | Destaques de vitrine | Controla onde o imóvel aparece (home, seções especiais) | Vitrines, filtros |
+| **C** | Badges flutuantes | Labels sobrepostos na imagem do card | Card (foto) |
+| **D** | Atributos financeiros | Checkmarks na caixa de valores lateral | Página (bloco valores) |
+| **E** | Atributos principais | Ícones com número (quartos, vagas, área) | Card + Página |
+| **F** | Situações/qualificações | Informações de qualificação (averbado, escriturado, judicial) | Página (seção própria) |
+
+**Cada CRM resolve essas categorias de forma diferente** — um usa array, outro usa booleans, outro usa tags. O agente consulta a FICHA_TECNICA pra saber como mapear.
+
+---
+
+## WIREFRAMES DE REFERÊNCIA
+
+O agente pode (e deve) desenhar wireframes ASCII pra validar a organização dos campos ANTES de implementar. Abaixo os wireframes de referência do card e da página.
+
+### Wireframe do Card
+
+```
+┌─────────────────────────────────────────┐
+│  ┌───────────────────────────────────┐  │
+│  │         📷 FOTO DO IMÓVEL         │  │
+│  │                                   │  │
+│  │  ┌──────┐ ┌────────┐    BADGES   │  │
+│  │  │ MCMV │ │Permuta │             │  │
+│  │  └──────┘ └────────┘             │  │
+│  │                        ┌───────┐  │  │
+│  │                        │  ❤️   │  │  │
+│  │                        └───────┘  │  │
+│  │            ╱╱╱╱╱╱╱╱╱╱╱            │  │
+│  │          ╱  Vendido  ╱   TARJA    │  │
+│  │        ╱╱╱╱╱╱╱╱╱╱╱╱╱             │  │
+│  └───────────────────────────────────┘  │
+│                                         │
+│  Casa à venda no Água Branca   TÍTULO   │
+│  Água Branca, F. BELTRÃO | #79 END+REF │
+│  R$ 650.000,00                  PREÇO   │
+│                                         │
+│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐   │
+│  │  🛏️  │ │  🛏️  │ │  🚿  │ │  🚗  │   │
+│  │  3   │ │  1   │ │  2   │ │  2   │   │
+│  │quart.│ │suíte │ │banh. │ │vagas │ ATTRS│
+│  └──────┘ └──────┘ └──────┘ └──────┘   │
+│  ┌──────┐ ┌──────┐                      │
+│  │180m² │ │250m² │                      │
+│  │priv. │ │total │                      │
+│  └──────┘ └──────┘                      │
+│                                         │
+│  👤 Elvis Ghisi | CRECI 123    CORRETOR │
+└─────────────────────────────────────────┘
+```
+
+### Wireframe da Página
+
+```
+╔═══════════════════════════════════╦═══════════════════════╗
+║       BLOCO CENTRAL               ║    BLOCO LATERAL      ║
+║                                   ║                       ║
+║  ── Ficha do Imóvel ──            ║  Valor venda:         ║
+║  Descrição do imóvel...           ║  R$ 650.000,00        ║
+║                                   ║  ☑ MCMV               ║
+║  ── Principal ──                  ║  ☑ Aceita permuta     ║
+║  3 Dormitórios | 1 Suíte         ║                       ║
+║  2 Banheiros | 2 Vagas           ║  Valor locação:       ║
+║  1 Sala | 1 Cozinha              ║  R$ 2.500,00          ║
+║  250m² total | 180m² priv.       ║  Condomínio: R$ 300   ║
+║  Tipo: Casa | Op: Venda          ║  IPTU: R$ 85          ║
+║  ☑ MCMV | ☑ Permuta              ║  Taxa lixo: R$ 25     ║
+║                                   ║                       ║
+║  ── Características ──            ║  👤 Elvis Ghisi       ║
+║  ☑ Churrasqueira | ☑ Elevador    ║  [Enviar mensagem]    ║
+║  ☑ Cozinha planejada             ║  [WhatsApp]           ║
+║  Piso: Porcelanato               ║                       ║
+║  Teto: Laje | Forro: Gesso       ║                       ║
+║                                   ║                       ║
+║  ── Segurança ──                  ║                       ║
+║  ☑ Interfone | ☑ Murado          ║                       ║
+║  ☑ Portão eletrônico             ║                       ║
+║                                   ║                       ║
+║  ── Lazer ──                      ║                       ║
+║  ☑ Piscina | ☑ Academia          ║                       ║
+║  Aquecimento: Gás                ║                       ║
+║  Posição solar: Norte            ║                       ║
+║                                   ║                       ║
+║  ── Localização ──                ║                       ║
+║  Apto: 304 | Bloco: 1           ║                       ║
+║  Andar: 3                        ║                       ║
+║                                   ║                       ║
+║  ── Rural ──                      ║                       ║
+║  ☑ Rio | ☑ Mina                  ║                       ║
+║  Alqueires: 10 | Hectares: 24   ║                       ║
+║                                   ║                       ║
+║  ── Informações adicionais ──     ║                       ║
+║  Pintura: Acrílica               ║                       ║
+╚═══════════════════════════════════╩═══════════════════════╝
+```
+
+Ao trocar de CRM, desenhar wireframes atualizados com os campos do novo CRM pra validar a organização antes de implementar.
+
+---
+
+## CARD DE IMÓVEL (Listagem)
+
+O card tem áreas de dados configuráveis:
+
+### 1. Tarjas (stripes)
+- **Visual:** Ribbon diagonal sobre a foto
+- **Propósito:** Indicar INDISPONIBILIDADE (Vendido, Alugado, Reservado, etc.)
+- **Fonte:** `getFieldsCardStripes()` → lê campo de situação do CRM
+- **Regra:** Só exibir pra estados de indisponibilidade. Disponível = sem tarja.
+
+### 2. Badges (labels flutuantes na foto)
+- **Visual:** Labels pequenos sobrepostos à foto
+- **Propósito:** Indicar DESTAQUES POSITIVOS
+- **Fonte:** `getFieldsDestaquesLabels()` → campos boolean/flag do CRM
+- **Regra:** Pode ter até ~7 badges configurados, mas raramente mais de 2-3 aparecem ao mesmo tempo num imóvel.
+- **Exemplos comuns:** MCMV, Permuta, Financiável, Lançamento, Exclusivo, Mobiliado, Baixou o preço
+
+### 3. Atributos com ícone (destaques da ficha)
+- **Visual:** Ícones com valor (quartos, suítes, banheiros, vagas, área)
+- **Fonte:** `getFieldsDestaquesComIcones()` → campos base Horizon
+- **Campos fixos:** dormitorios, suites, banheiros, vagas_garagem, area_privativa, area_total
+- **Regra:** Estes são campos BASE Horizon. Iguais em qualquer CRM.
+
+### 4. Campos padrão
+- Título, endereço (bairro + cidade), referência, preço(s)
+- Não vêm de listas — são direto do property
+
+### Select Fields
+- `select-fields.config.ts` → `cardList`
+- DEVE incluir TODOS os campos usados por tarjas, badges e atributos
+- Se o campo não tiver no select, o card não recebe e não exibe
+
+---
+
+## DISPLAY CONFIG (flags de layout da página)
+
+A página do imóvel usa flags tipadas por feature (`display-config/derive.ts`). Essas flags controlam quais blocos, botões e funcionalidades aparecem.
+
+### REGRA CRÍTICA: Preencher TODAS as flags
+
+Se uma flag não for preenchida, a feature correspondente fica **DESATIVADA** na página. Isso é um problema sério — desativa street view, botões de solicitação, seção de financiamento, etc.
+
+**Ao trocar de CRM, o agente DEVE:**
+1. Ler a FICHA_TECNICA do CRM pra saber quais campos nativos resolvem cada flag
+2. Se o CRM tem campo nativo (ex: `has_video`) → usar direto
+3. Se o CRM NÃO tem campo nativo → tentar resolver via:
+   - **Tags** (se o CRM suporta tags)
+   - **Campos customizados / fields[]** (campo sem valor = flag ativa)
+   - **Combinação de outros campos** (ex: `is_venda` derivado de `operacao.includes('venda')`)
+4. Se não tem como resolver de jeito nenhum → documentar como limitação do CRM
+
+**O objetivo é PREENCHER o máximo possível de flags**, porque cada flag desativada = feature desativada na página.
+
+### Estrutura
+```
+core/item/display-config/
+├── types.ts          → Interfaces tipadas por feature (has_* pattern)
+├── derive.ts         → ÚNICO arquivo que muda ao trocar de CRM
+└── extensions/
+    └── index.ts      → Customizações do cliente (Etapa 3)
+```
+
+---
+
+## PÁGINA DO IMÓVEL (Detalhe)
+
+### BLOCO CENTRAL — Ficha do Imóvel (`PropertyInfoBlock`)
+
+Seções organizadas de forma concisa:
+
+#### Princípios de organização
+1. **Sem seções com poucos campos** — Não criar título de seção pra 2-3 campos. Juntar com seção relacionada.
+2. **Enums junto com booleans** — Enums de uma categoria (ex: aquecimento, posição solar) vão na mesma seção dos booleans dessa categoria (ex: Lazer).
+3. **Acabamentos junto com características** — Piso, teto, forro são poucos campos, vão junto com as características.
+4. **Situação comercial na Principal** — MCMV, permuta, situação vão na ficha técnica principal.
+5. **Campos customizados** — Exibir os `fields[]` restantes como seção final.
+
+#### Seções
+1. **Principal** — Contadores (quartos, suítes, banheiros, vagas, salas, cozinhas, closets, varandas, lavabos), áreas, tipo, operação, situação comercial (MCMV, permuta, etc.)
+2. **Características + Acabamentos** — Booleans do array de features + campos de acabamento (piso, teto, forro, etc.)
+3. **Segurança** — Booleans do array de segurança
+4. **Lazer** — Booleans do array de lazer + enums (aquecimento, posição solar, posição quadra)
+5. **Dimensões** — Todas as medidas do terreno e áreas adicionais
+6. **Localização complementar** — Apartamento, bloco, andar, quadra, lote
+7. **Rural** — Booleans do array rural + campos numéricos rurais
+8. **Campos extras** — `fields[]` JSONB restantes como key-value
+
+### BLOCO LATERAL — Caixa de Valores
+
+Organizado por operação:
+
+#### Venda (se operação inclui "venda")
+```
+Valor de venda: R$ XXX.XXX,XX
+---
+Atributos de venda:
+☑ MCMV (se disponível no CRM)
+☑ Aceita permuta
+☑ Aceita financiamento
+☑ Outros flags do CRM
+```
+
+#### Locação (se operação inclui "locação")
+```
+Valor de locação: R$ X.XXX,XX
+---
+Valores monetários:
+Condomínio: R$ XXX,XX
+IPTU: R$ XX,XX
+Taxa de lixo: R$ XX,XX
+(outras taxas do CRM)
+---
+Atributos de locação:
+(tipos de garantia, caução, etc. — quando disponíveis)
+```
+
+---
+
+## COMO ADICIONAR UM CAMPO NA BUSCA
+
+Para um campo aparecer como filtro na busca avançada, são necessários **3 arquivos**:
+
+1. **`features/search-list/schema.ts`** — Adicionar campo no Zod (ex: `meu_campo: z.boolean().optional()`)
+2. **`features/search-list/config/schema.ts`** — Adicionar config do facet (tipo, label, operator, options, facetConfig)
+3. **`features/search-list/components/fields/*.tsx`** — Adicionar num componente existente ou criar novo
+
+**Sem o passo 1:** O campo é ignorado pela API. **Sem o 2:** Sem contagem. **Sem o 3:** Não aparece na UI.
+
+**Booleans agrupados** (MCMV, Permuta, etc.) → adicionar em `SituacaoComercialField.tsx` no array `GROUPS[0].items[]`
+
+---
+
+## REGRA OBRIGATÓRIA AO TROCAR DE CRM
+
+Ao configurar um novo CRM, SEMPRE:
+
+1. **Ler a FICHA_TECNICA** do CRM → saber quais campos existem
+2. **`fields-lists.ts`** → Configurar TODAS as funções getter pra cada seção (tarjas, badges, valores, ficha técnica, características, segurança, lazer, dimensões, localização, rural)
+3. **`select-fields.config.ts`** → Garantir que cardList tem todos os campos de tarjas + badges
+4. **`PropertyInfoBlock.tsx`** → Ajustar seções da ficha do imóvel
+5. **Caixa de Valores** → Ajustar valores monetários e flags por operação
+6. **`useLayoutManager.ts`** → Ajustar detecção de vendido/alugado, streetview, geo
+7. **Testar com imóvel completo** → Verificar que todas as seções renderizam
+
+---
+
+## NAVEGAÇÃO DINÂMICA
+
+Os menus de Venda/Locação são dinâmicos — children vêm de facets da API:
+
+- **Fetcher:** `capabilities/navigations/fetchers/property.ts`
+- **Service:** `capabilities/navigations/navigation.service.ts` (com cache)
+- **Provider:** `capabilities/navigations/NavigationProvider.tsx` → `useNavigation()`
+- **Regra:** Ao trocar de CRM, menus se adaptam automaticamente (dados da API)
+- **Counts:** Cada child do menu mostra contagem real
+
+---
+
+## VITRINE DA HOME
+
+- **Componente:** `customs/property-showcase/PropertyShowcaseSectionSSR.tsx`
+- **Filtro padrão:** `{ operacao: ["venda"], destaque: true }`
+- **Campo `destaque`:** Existe pra alimentar esta vitrine. SEMPRE configurar.
+- **Regra:** O SSR é a fonte de verdade dos filtros (não duplicar defaults no client)
+
+---
+
+## CATEGORIAS DA HOME
+
+- **Arquivo:** `home/sections/categories-carousel/categories-data.ts` (ou guia-de-compra)
+- **Cada card tem:** title, image, icon, link, filters (pra contagem dinâmica)
+- **Contagem:** Via `batchSearch` usando os `filters` de cada categoria
+- **Regra ao trocar CRM:** SEMPRE atualizar os tipos nos links e filters. Cada CRM tem tipos diferentes.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@horizon-framework/website-dev-docs",
+  "version": "2.3.0",
+  "description": "Documentacao inteligente da plataforma Horizon para agentes de IA. Instale para tornar seu agente mais inteligente.",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "horizon",
+    "docs",
+    "ai-agent",
+    "platform",
+    "real-estate"
+  ]
+}