Documentação técnica · v4 (auditoria de implantação)

Plano de Implantação — Sistema Completo

Este plano cruza o catálogo SISTEMA_COMPLETO.md (15 módulos, visão de longo prazo) com o que já está rodando na plataforma. Cada módulo tem status atual, o que falta e uma onda de implantação recomendada. Banco: Supabase (PostgreSQL) já conectado, com PostGIS habilitado.

1. Visão

O produto nasce como MVP hiperlocal em Formosa-GO e evolui para plataforma multi-cidade com diferencial geoespacial rural (SIGEF/INCRA/CAR), CRM, IA aplicada, financiamento, marketplace de serviços e mobile. A base atual (contas, anúncios, busca pública, leads, moderação, SEO técnico e instrumentação) já valida o loop central e sustenta as próximas ondas.

2. Resumo do status atual

Das 8 fases do MVP inicial, 7 estão em produção; apenas cobrança (Stripe) segue pendente por dependência externa de gateway. Após a auditoria mais recente, cerca de 80% dos itens do catálogo estão cobertos. Entraram em produção desde a última revisão: cofre próprio de chaves no painel admin (Lovable AI desativado, tudo via OpenAI), WhatsApp real pela Evolution API (instância + QR Code + envio), motor de captação externa de anúncios, radar de leads com score determinístico, pedidos de busca com distribuição automática, módulo de locação (contratos, cobranças, recibos, DIMOB), portal do proprietário, contratos assistidos por IA, painel de território e redes sociais.

Fases MVP

7 / 8

em produção

Módulos cobertos

15 / 15

parcial ou completo

Ondas planejadas

A/B/C/D/E/F/G — G em curso

3. Status por módulo (SISTEMA_COMPLETO)

1. Busca e Descoberta

Parcial

Já implantado

Busca textual e filtros combináveis (tipo, transação, bairro, preço, quartos, vagas, suítes)
Ordenação por recentes, menor e maior preço
Página de detalhe SSR com galeria e características do imóvel
Mapa inteligente estilo Uber: zoom por scroll, marcadores SVG animados por tipo/transação e desenho livre de polígono para filtrar por área
Favoritos, comparador lado a lado e alertas salvos por filtros
Filtro MCMV (venda até R$ 350k, aceita financiamento)
Custo mensal real no anúncio (aluguel + IPTU/12 + condomínio + taxas fixas)

Falta

Autocomplete de bairros/empreendimentos e busca por código
Clusters no mapa e busca por raio
Camada rural SIGEF/INCRA/CAR e POIs (escolas, comércio)
Busca semântica/conversacional e por imagem

2. Publicação e Gestão de Anúncios

Parcial

Já implantado

Cadastro urbano/rural (m² e hectares), condomínio, IPTU anual, taxas fixas, situação documental, exclusividade
Edição, pausar/reativar/excluir com preservação de histórico
Upload com recorte obrigatório em popup (1600x1200) já na criação do anúncio, capa e ordenação (bucket privado + URLs assinadas)
Checklist de características pré-preenchido e extensível, exibido no anúncio
Geolocalização bidirecional: endereço ↔ pino no mapa com geocodificação
Descrição automática por IA (OpenAI) com curadoria humana
Garantias locatícias (caução, fiador, seguro-fiança, título de capitalização) + meses de caução
Motor de captação externa de anúncios (Firecrawl + extração por IA) em /captacao com ficha detalhada e contato

Falta

Compressão automática de imagens no upload
Fotos 360°, vídeos, tour virtual e plantas baixas
Classificação automática de imagens (cômodos/características)
Staging virtual com IA
Importação em lote (planilha) e integração com CRMs (Kenlo, Jetimob, Imoview)
Publicação cruzada em portais nacionais

3. Leads, CRM e Relacionamento

Implantado

Já implantado

Painel de leads com status (novo/em atendimento/ganho/perdido) e Kanban de funil
Formulário 'Tenho interesse / Saber mais / Reservar' no anúncio gerando lead para o corretor
Detalhe do lead com resposta rápida enviada por WhatsApp via Evolution API
Notificação em tempo real via Supabase Realtime
Anotações, timeline e follow-up programado por lead
Distribuição automática entre corretores (round-robin por menor carga) configurável em /admin/distribuicao
Pedidos de busca do comprador (ficha na landing page) distribuídos automaticamente aos corretores
Agenda de visitas com status agendada/confirmada/realizada/cancelada/no-show e feedback pós-visita
Radar de leads (/radar) com score determinístico de engajamento, intenção e recência
Rastreamento de identidade do visitante em 6 camadas alimentando o score
Assistente Comercial com briefing diário no painel e no WhatsApp, com botão de teste de envio

Falta

Fallback por e-mail transacional (Resend)
Sincronização da agenda com Google Calendar / iCal
Chat interno na plataforma

4. Contas, Perfis e Papéis

Parcial

Já implantado

Papéis comprador, corretor, imobiliária, proprietário e admin (user_roles + has_role)
Imobiliárias com membros (agencies + agency_members: owner/manager/agent)
Autenticação por e-mail/senha com perfil (nome, telefone)
Selo CRECI verificado (painel, perfil, admin e página do imóvel) e verificação em /admin/tools
Reputação e avaliações de anunciantes (advertiser_reviews)
Vitrine pública de corretores e imobiliárias na home (public_advertisers)
Página pública da imobiliária (/imobiliaria/$slug)

Falta

Perfil dedicado de construtora/incorporadora com página de empreendimento
Perfil de loteadora com mapa de lotes
Permissões granulares por ação

5. Monetização e Comercial

Parcial

Já implantado

Destaque avulso em três tiers (bronze/prata/ouro) atribuído pelo admin, com featured_until e featured_tier
API pública REST /api/public/v1/listings com Bearer token, escopos, hash SHA-256 e revogação
Página /parceiros para geração e gestão de chaves — base do white-label
Carteira de Tokens de IA por usuário (/ia-tokens) com cota mensal e controle de consumo
Marketplace de serviços complementares (Módulo 15) em produção

Falta

Assinatura recorrente por perfil (Stripe: Pix + cartão) — tabelas já modeladas
Compra de créditos de impulsionamento pelo próprio anunciante
Contratos por projeto para construtoras/loteadoras
API paga de dados geoespaciais rurais
White-label multi-cidade self-service
Programa de indicação

6. Inteligência Artificial

Parcial

Já implantado

Lovable AI desativado: todo texto do sistema roda na chave própria de OpenAI cadastrada no cofre
Descrição automática de anúncio (botão ✨ no formulário)
Chatbot de qualificação em cada página de imóvel
IA Consultora (/consultora) e assistente comercial com briefing diário
Extração por IA das captações externas (ficha do imóvel a partir da página de origem)
Redação assistida de contratos (/contracts) e conteúdo para redes sociais (/redes)
Recomendação personalizada a partir dos favoritos
AVM básica por comparáveis (média por m²/ha, faixa P25–P75)
Score de leads 100% determinístico (sem IA), conforme decisão de produto

Falta

Busca semântica/conversacional e por imagem
Classificação automática de imagens
Detecção automática de spam/duplicidade por IA
Staging virtual

7. Dados Públicos e Diferencial Geoespacial

Parcial

Já implantado

PostGIS habilitado e lat/long em listings com geocodificação no cadastro
Painel de território (/admin/territorio e /territorio) com dados por bairro e cobertura
Mercado (/mercado) com indicadores locais agregados

Falta

Ingestão SIGEF/INCRA/CAR e exibição no anúncio rural
Camadas ambientais (FUNAI, ICMBio, IBAMA, PRODES, IBGE)
Laudos e relatórios geoespaciais vendáveis via API

8. Financiamento e Crédito

Parcial

Já implantado

Simulador SAC/Price em /financiamento com sliders de entrada/prazo
Comprometimento de renda e cartão de elegibilidade MCMV
Link 'Simular financiamento deste imóvel' na página de detalhes
Filtro MCMV na busca

Falta

Pré-análise via Open Finance
Acompanhamento do status de aprovação
Integração direta com Caixa e outros bancos parceiros

9. Documentação e Jurídico

Parcial

Já implantado

Situação documental no anúncio (escritura, contrato, inventário, financiado)
Propostas eletrônicas com aceite LGPD (IP, user-agent, timestamp) e contraproposta
Painel /proposals para aceitar / em análise / recusar
Contratos (/contracts) com geração e revisão assistida por IA e painel por contrato

Falta

Verificação assistida de matrícula/ônus/certidões
Assinatura eletrônica reconhecida (D4Sign / ClickSign)
Consulta assistida a cartórios

10. Condomínios e Locação Avançada

Parcial

Já implantado

Módulo de locação completo: contratos de aluguel, reajuste, cobranças mensais e recibo por cobrança
Relatório DIMOB (/rentals/dimob) para prestação de contas anual
Portal do proprietário: patrimônio, financeiro, contratos e documentos
Garantias locatícias por anúncio com meses de caução
Modelo de vistoria pronto (inspections com checklist, fotos e assinatura)

Falta

Módulo básico de administração de condomínio
UI de vistoria entrada/saída
Repasse automatizado ao proprietário via gateway

11. Expansão e Multi-Cidade

Parcial

Já implantado

Modelo multi-tenant desde a origem (cidade/estado em agencies e listings)
Tabela regions com preços regionalizados de destaque, bairros e seed de Formosa-GO e Planaltina-GO
Painel de território com cobertura por bairro

Falta

Surfar regions na UI (seletor de cidade na home e hero regional)
Onboarding automatizado de nova cidade pelo admin
Dashboard consolidado multi-cidade
Playbook de captação local replicável

12. Analytics, BI e Relatórios

Parcial

Já implantado

Tabela events + trackEvent (view, contact_click, lead_created, search_performed, report_submitted)
Rastreamento de profundidade de visualização por anúncio
Painel /analytics do anunciante e analytics por anúncio (7/30/90d)
Radar com ranking determinístico de oportunidades (/oportunidades e /radar)

Falta

Benchmarking de preços por bairro/região
Exportação e integração com BI externo (CSV, webhook)
Dashboard consolidado para imobiliárias

13. Segurança, Confiança e Compliance

Parcial

Já implantado

Denúncias (listing_reports) com fila e ações em /admin/moderation
RLS ativa em todas as tabelas, escopadas por auth.uid()
Consentimento LGPD explícito no envio de lead
Cofre de chaves no servidor (/admin/integracoes): valores nunca retornam ao navegador, apenas trecho mascarado
Trilha de auditoria administrativa (/admin/audit)
LGPD self-service em /profile: exportar dados (JSON) e solicitar exclusão

Falta

Detecção automática de duplicidade/spam por IA
Backups automáticos testados e política formal

14. Mobile e Multiplataforma

Parcial

Já implantado

Web responsivo em Tailwind, mobile-first
PWA: manifest com ícone, theme-color e atalhos (Buscar / Anunciar / Simulador)
Service Worker com cache do shell e fallback offline

Falta

Push notifications reais (VAPID)
Otimizações para conexão lenta
App nativo iOS/Android com paridade

15. Marketplace de Serviços Complementares

Parcial

Já implantado

Página pública /servicos com filtro por categoria e cidade
Cadastro pelo prestador em /services/new (9 categorias)
Modelo com verificação, rating e vínculo opcional a regions

Falta

Integração com seguradoras (fiança/residencial)
Empresas de mudança e pós-compra
Avaliação/comentários do prestador pelo cliente
Programa de comissão e leads pagos para prestadores

4. Ondas de implantação (a partir de agora)

Sequência priorizada por dependência técnica, retorno para o anunciante e desbloqueio de receita. Cada onda entrega valor visível e é auditável nas métricas já instrumentadas.

Onda A — Monetização + Confiança do anunciante

Parcial

Fechar o loop econômico e destravar receita recorrente.

✔ Módulo 4: selo CRECI verificado (CreciBadge em painel, perfil, admin e página do imóvel) + verificação pelo admin em /admin/tools
✔ Módulo 4: reputação/avaliações de anunciantes (advertiser_reviews)
✔ Módulo 5: destaque avulso em três tiers (bronze/prata/ouro) atribuído pelo admin em /admin/tools
✔ Módulo 13: trilha de auditoria administrativa (admin_audit_log via logAdminAction)
Pendente: assinatura recorrente Stripe (Pix + cartão) — tabelas subscription_plans e subscriptions já modeladas, integração de pagamento a fazer depois
Pendente: compra self-service de créditos de destaque pelo próprio anunciante (hoje só o admin atribui)
Pendente: fallback por e-mail transacional (Resend) no envio de lead

Onda B — CRM operacional + agenda

Implantado

Transformar leads em pipeline e reduzir tempo de resposta.

✔ Módulo 3: Kanban de funil (novo → em atendimento → ganho/perdido) em /leads
✔ Módulo 3: anotações, timeline e follow-up programado (lead_notes + follow_up_at)
✔ Módulo 3: distribuição automática entre corretores, configurável em /admin/distribuicao
✔ Módulo 3: pedidos de busca do comprador na landing page distribuídos automaticamente
✔ Módulo 3: agenda de visitas com feedback pós-visita
✔ Módulo 3: resposta rápida ao lead por WhatsApp (Evolution API) e briefing diário do Assistente Comercial
✔ Módulo 12: radar de leads com score determinístico (engajamento, intenção, recência)
Pendente: sincronização com Google Calendar / iCal e lembretes automáticos de visita

Onda C — Discoverability avançada

Parcial

Aumentar conversão de busca e ativar o diferencial geoespacial.

✔ Módulo 1: mapa inteligente com marcadores animados por tipo/transação e desenho livre de polígono para filtrar por área
✔ Módulo 1: favoritos, comparador lado a lado e alertas salvos por filtros
✔ Módulo 2: geolocalização bidirecional endereço ↔ pino no cadastro do anúncio
Pendente: clusters no mapa, busca por raio e autocomplete de bairros/empreendimentos
Pendente: Módulo 7 — camadas SIGEF/INCRA/CAR sobre o mapa para imóveis rurais
Pendente: Módulo 2 — compressão automática de imagens, plantas baixas e vídeos

Onda D — IA aplicada

Parcial

Reduzir atrito de publicação e qualificar leads 24/7.

✔ Módulo 6: migração completa para a chave própria de OpenAI (Lovable AI desativado) com cofre no painel admin
✔ Módulo 6: descrição automática de anúncio, chatbot de qualificação, IA Consultora e conteúdo para redes sociais
✔ Módulo 6: extração por IA das captações externas e redação assistida de contratos
✔ Módulo 6: recomendação personalizada e AVM básica por comparáveis
✔ Módulo 12: score de leads determinístico (sem IA) com rastreamento de identidade em 6 camadas
Pendente: classificação automática de imagens e detecção IA de spam/duplicidade

Onda E — Jurídico, financiamento e locação

Parcial

Cobrir a jornada completa de compra e aluguel.

✔ Módulo 8: simulador SAC/Price em /financiamento, filtro MCMV e link a partir do anúncio
✔ Módulo 9: proposta com aceite eletrônico (IP, user-agent, timestamp), contraproposta e painel /proposals
✔ Módulo 9: contratos com geração e revisão assistida por IA
✔ Módulo 10: locação completa — contratos, reajuste, cobranças, recibos e DIMOB
✔ Módulo 10: portal do proprietário (patrimônio, financeiro, contratos, documentos)
✔ Módulo 13: exportação LGPD dos meus dados e solicitação de exclusão no /profile
Pendente: vistoria entrada/saída (tabela inspections pronta, UI a fazer) e assinatura eletrônica reconhecida

Onda F — Escala: multi-cidade, mobile e marketplace

Parcial

Replicar o playbook e ampliar o ecossistema.

✔ Módulo 11: tabela regions com precificação regionalizada, bairros e seed de Formosa-GO e Planaltina-GO
✔ Módulo 14: PWA — manifest, ícone, atalhos e Service Worker com cache offline
✔ Módulo 15: marketplace de serviços em /servicos com cadastro pelo próprio prestador
✔ Módulo 5: API pública REST autenticada por Bearer token e página /parceiros — base do white-label
Pendente: surfar regions na UI (seletor de cidade na home + hero regional)
Pendente: push notifications reais (VAPID)
Pendente: onboarding automatizado de novas cidades pelo painel admin

Onda G — Operação própria: cofre de chaves, WhatsApp e captação

Parcial

Tirar o sistema de dependências gerenciadas e operar com infraestrutura própria.

✔ Cofre interno de chaves em /admin/integracoes (OpenAI, ElevenLabs, Evolution) — valores só mascarados no navegador
✔ Lovable AI desativado; todo texto gerado passa pela chave própria de OpenAI
✔ Evolution API: criação de instância, QR Code, status de conexão e envio real de mensagens
✔ Resposta rápida ao lead por WhatsApp e teste de envio do briefing diário
✔ Motor de captação externa com Firecrawl em modo stealth e extração por IA
✔ Carteira de Tokens de IA por usuário com cota mensal
Pendente: webhook de entrada do WhatsApp (respostas do cliente caindo no CRM)
Pendente: fila de reenvio e alertas quando a instância cair

5. Stack técnico

Frontend: React 19 + TanStack Start (SSR) + Tailwind v4.
Banco: Supabase (PostgreSQL) com PostGIS.
Auth: Supabase Auth (e-mail/senha), papéis em user_roles.
Storage: bucket privado listing-photos com URLs assinadas.
Servidor: createServerFn e rotas /api/public/* para webhooks.
Realtime: Supabase Realtime para leads.

6. Integrações externas

WhatsApp: Evolution API (ativa) — instância, QR Code, status de conexão e envio real de mensagens (resposta ao lead e briefing diário). Chave única gerenciada no cofre em /admin/integracoes. Webhook de entrada (respostas do cliente) ainda pendente.
IA: OpenAI com chave própria (ativa) — descrição de anúncio, chatbot, IA Consultora, contratos, captação, redes e briefing. O Lovable AI Gateway está desativado. Classificação de imagens e detecção de spam seguem pendentes.
Captação externa: Firecrawl (ativo, modo stealth) para coletar anúncios de fontes externas, com extração estruturada por IA.
Voz: ElevenLabs (opcional) — chave gerenciada no cofre para o assistente falado.
Gateway de pagamento: Stripe (pendente na Onda A) com Pix e cartão para assinatura e destaque avulso.
Mapas: Google Maps Platform (ativo) — mapa inteligente com marcadores animados, desenho de polígono, geocodificação e seletor de coordenadas. Clusters e camadas rurais SIGEF/INCRA/CAR pendentes.
E-mail transacional: Resend (pendente na Onda A) para fallback de notificação de lead e comunicações de conta.
Dados geoespaciais: SIGEF/INCRA/CAR (Onda C/E) via pipelines dedicados no Supabase.
Assinatura eletrônica: D4Sign ou ClickSign (pendente na Onda E) para contratos completos — hoje há apenas aceite click-through com IP/UA/timestamp em proposals.

7. Métricas de sucesso

Nº de imóveis publicados (meta inicial: 100)
Imobiliárias-âncora ativas (meta: 5 a 10)
Corretores ativos (meta: 20 a 50)
Leads reais gerados por mês (meta: 100/mês)
Tempo até a primeira resposta ao lead
Conversão de plano gratuito para pago (a partir da Onda A)
Tráfego orgânico em termos locais chave
Assinantes ativos e MRR (Onda A em diante)

8. Backlog priorizado (próximas entregas)

Lacunas confirmadas na auditoria de código, ordenadas por impacto em receita, conversão e conformidade. Este é o roteiro imediato, acima de qualquer novo módulo.

Webhook de entrada do WhatsApp (Módulo 3) — as respostas do cliente na Evolution API devem cair no CRM e atualizar o lead automaticamente.
Regions na UI (Módulo 11) — seletor de cidade ativa na home + hero regional puxando hero_headline e featured_neighborhoods. Tabela e seed prontos.
Compra de destaque self-service (Módulo 5) — hoje o admin atribui manualmente. Fluxo do anunciante escolher tier + período, com featured_until e featured_tier. Preços vêm de regions.
Assinatura recorrente Stripe (Módulo 5) — Pix + cartão, gestão de plano no painel. Configuração de pagamento fica para quando o usuário liberar as chaves.
Fallback de e-mail Resend (Módulos 3/13) — envia notificação ao anunciante quando o lead entra fora do WhatsApp e para lembretes de visita.
UI de vistoria entrada/saída (Módulo 10) — tabela inspections já existe com checklist e fotos; falta a tela para o corretor/vistoriador preencher e o inquilino assinar.
Onboarding self-service de nova cidade (Módulo 11) — admin cria region + define preços de destaque sem precisar de migration manual.
Assinatura eletrônica reconhecida (Módulo 9) — D4Sign ou ClickSign para contratos completos, além do aceite click-through atual.
Push notifications VAPID (Módulo 14) — completa o PWA para retenção de compradores e corretores.
Camadas rurais SIGEF/INCRA/CAR (Módulo 7) — pipeline de ingestão + camada sobre o Google Maps; ativa o diferencial rural.

Fonte: SISTEMA_COMPLETO.md v1.0 do Investe Formosa, cruzado com o estado atual do banco (Supabase) e das rotas em produção.