📄 Data4Build — Documentação Técnica Completa
⚡ Data4Build
Plataforma de Inteligência para o Mercado de Construção Civil
DOCUMENTAÇÃO TÉCNICA COMPLETA
Backend · Regras de Negócio · Entidades · Funções · Fluxos
Versão 1.0 · Gerado em 17 de novembro de 2026

📋 Sumário

  1. 1.Visão Geral da Plataforma
  2. 2.Arquitetura e Stack Tecnológico
  3. 3.Entidades do Banco de Dados
  4. 4.Regras de Negócio — Planos e Assinaturas
  5. 5.Regras de Negócio — Score de Match
  6. 6.Regras de Negócio — SuperMatch
  7. 7.Fluxo de Onboarding
  8. 8.Fluxo de Pagamento (Stripe)
  9. 9.Funções Backend (Edge Functions)
  10. 10.Automações e Tarefas Agendadas
  11. 11.Sistema de Emails
  12. 12.Importação de Obras (Fontes de Dados)
  13. 13.Secrets e Variáveis de Ambiente
  14. 14.Segurança e Controles de Acesso
  15. 15.Glossário

1. Visão Geral da Plataforma

O Data4Build é uma plataforma SaaS B2B que conecta fornecedores de materiais e serviços da construção civil a obras em andamento no Brasil. A plataforma coleta, estrutura e enriquece dados de obras de múltiplas fontes públicas, aplica algoritmos de compatibilidade e entrega oportunidades qualificadas para fornecedores cadastrados.

Personas

PersonaDescriçãoAcesso
FornecedorEmpresa fornecedora de materiais/serviços para construção civilApp principal (mobile-first)
AdminGestor interno da plataforma Data4BuildPainel admin interno
VisitanteSem conta — acessa landing pageLanding page pública

URLs Principais

URLPágina
/LandingLanding page pública
/OnboardingCadastro de novo fornecedor
/ClientLoginLogin do fornecedor
/HomeDashboard principal do fornecedor
/OportunidadesLista de obras compatíveis
/PipelineGestão do pipeline de vendas
/RadarRadar de obras em mapa
/NotificacoesCentral de alertas
/SupplierAccountPerfil e assinatura
/CheckoutInicialização do checkout Stripe
/TrialExpiradoTela de trial expirado
/AdminDashboardPainel admin (role = admin)

2. Arquitetura e Stack Tecnológico

CamadaTecnologiaDetalhes
FrontendReact 18 + ViteSPA, Tailwind CSS, shadcn/ui, framer-motion
Backend / BaaSBase44 PlatformBanco de dados NoSQL, autenticação, SDK
Edge FunctionsDeno DeployFunções serverless em JS/TS
PagamentosStripeCheckout Sessions + Webhooks
EmailResend + Base44 SendEmailTransacional e sequências de onboarding
Mapasreact-leaflet + NominatimOpenStreetMap para geocoding e exibição
PDFjsPDFGeração de orçamentos em backend
Dados externosObrasGov API, PNCP, CNOFontes públicas de obras

Autenticação

O app é público (não requer login Base44). A autenticação do fornecedor é gerenciada via localStorage:

  • localStorage.supplier_id — ID do registro Supplier no banco
  • localStorage.supplier_token — Token gerado no login (base64 legacy)

⚠️ Importante — App Público

Por ser app público, todas as Edge Functions que operam sobre dados de fornecedor devem usar base44.asServiceRole ao invés de base44.auth.me(). A autenticação por auth.me() retorna null em contexto público.


3. Entidades do Banco de Dados

3.1 Supplier (Fornecedor)

Entidade principal. Representa um fornecedor cadastrado na plataforma.

CampoTipoDescriçãoValores
company_namestringNome da empresaObrigatório
emailemailEmail principal de contatoObrigatório
whatsappstringWhatsApp para contatoObrigatório
cnpjstringCNPJ da empresaOpcional
materialsarrayCategorias de materiais fornecidosVer enum abaixo
locationstringCidade/região de atuaçãoTexto livre
latitude / longitudenumberCoordenadas geográficasDecimal
service_radiusnumberRaio de atuação em km10, 30, 50, 100, 150
planstringPlano de assinatura atualtrial / starter / premium
trial_expires_atdatetimeData de expiração do trialISO 8601
onboarding_completedbooleanOnboarding foi concluídotrue/false
usernamestringUsername único para loginÚnico
password_hashstringSenha (armazenada como texto — ver aviso)Sensitivo

🚨 Pendência de Segurança — password_hash

Atualmente o campo password_hash armazena a senha em texto puro. A função authenticateSupplier compara diretamente supplier.password_hash !== password. Antes do Go Live em produção, implementar bcrypt para hash de senhas.

Enum: materials

ValorRótulo
estrutura_acoEstrutura / Aço
cimento_concretoCimento / Concreto
eletricaElétrica
hidraulicaHidráulica
iluminacaoIluminação
revestimentosRevestimentos
pisosPisos
esquadriasEsquadrias
impermeabilizacaoImpermeabilização
outrosOutros

3.2 Construction (Obra)

CampoTipoDescrição
namestringNome da obra
companystringNome da construtora
citystringCidade
addressstringEndereço completo
contact_name / contact_role / contact_phonestringDados do contato de compras
latitude / longitudenumberCoordenadas geocodificadas
phaseenumFase da obra: fundacao, estrutura, alvenaria, instalacoes, acabamento, entregue
statusenumem_andamento, planejada, finalizada
materials_neededarrayMateriais demandados pela obra (mesmo enum do Supplier)
units / area_m2numberUnidades e área
sourceenummanual, obrasgov, cno, pncp, csv
external_idstringID único da fonte externa (evita duplicatas)
scorenumberScore de match calculado (0–100)
pipeline_statusenumnone → contato_iniciado → orcamento_enviado → negocio_fechado
supermatch_activebooleanSuperMatch ativo no momento
supermatch_expires_atdatetimeExpiração do SuperMatch
views_count / phone_clicks / whatsapp_clicksnumberMétricas de engajamento
contact_feedback_valid / invalidnumberVotos de validação do contato
valor_empenhado / valor_pagonumberDados financeiros (Portal Transparência)
data_quality_scorenumberScore de qualidade dos dados (0–100)
address_verified / email_valid / phone_validbooleanFlags de validação

3.3 Notification (Notificação)

CampoTipoDescrição
titlestringTítulo da notificação
bodystringCorpo da mensagem
typeenumsupermatch_activated, supermatch_expiring, supermatch_expired, reminder, pipeline_update
construction_id / construction_namestringObra relacionada
readbooleanLida ou não
created_bystringEmail do fornecedor dono da notificação

3.4 SuperMatchHistory

CampoTipoDescrição
construction_id / construction_namestringObra referenciada
activated_at / expires_atdatetimeJanela de ativação
pipeline_status_at_closeenumStatus do pipeline quando o SuperMatch foi encerrado
reminder_at / reminder_setdatetime/boolDados do lembrete
scorenumberScore no momento da ativação

3.5 AppConfig

CampoDefaultDescrição
suspicious_contact_threshold2Votos negativos para marcar contato suspeito
supermatch_duration_hours24Duração do SuperMatch em horas

4. Regras de Negócio — Planos e Assinaturas

4.1 Planos Disponíveis

PlanoValorObras VisíveisSuperMatchDuração
TrialGrátisAté 2Não7 dias a partir do cadastro
Starter12x R$ 1.290/mêsAté 101 por mêsContrato anual (12 meses)
Premium12x R$ 2.490/mêsIlimitadasIlimitadoContrato anual (12 meses)

4.2 Regras de Acesso por Plano (trialUtils)

// isTrialActive(supplier) → boolean
// Planos pagos (starter/premium) sempre retornam true.
// Plan 'trial': retorna true apenas se trial_expires_at > agora.

// isTrialExpired(supplier) → boolean
// Planos pagos NUNCA expiram (retorna false).
// Plan 'trial': sem data OU data passada = true.

// getVisibleLimit(supplier) → number
// premium  → Infinity
// starter  → 10
// trial    → 2

// canSeeSuperMatch(supplier) → boolean
// Apenas plan === 'premium'

4.3 Ciclo de Vida da Assinatura

  1. 1. Fornecedor se cadastra no Onboarding → conta criada com plan: "trial" e trial_expires_at = agora + 7 dias.
  2. 2. Se escolher plano pago no Onboarding → redirecionado para /Checkout?plan=starter|premium.
  3. 3. Checkout inicializa via createCheckout → gera URL do Stripe Checkout.
  4. 4. Após pagamento aprovado → Stripe dispara webhook checkout.session.completed.
  5. 5. stripeWebhook atualiza Supplier.plan para o plano pago e zera trial_expires_at.
  6. 6. Quando assinatura é cancelada → Stripe dispara customer.subscription.deleted.
  7. 7. stripeWebhook rebaixa Supplier.plan para "trial".

4.4 Price IDs Stripe (Test Mode)

PlanoPrice IDValor
Starterprice_1T7z1oPt4BGSaQVcBcPCZHW6R$ 1.290/mês
Premiumprice_1T7z1oPt4BGSaQVcKEabIL0ER$ 2.490/mês

5. Regras de Negócio — Score de Match

O score de compatibilidade entre um fornecedor e uma obra é calculado em dois eixos, totalizando 0 a 100 pontos:

5.1 Materiais (até 50 pts)

// Intersecção entre supplier.materials e construction.materials_needed
const matches = supplierMats.filter(m => constructionMats.includes(m)).length;
score += Math.round((matches / Math.max(supplierMats.length, constructionMats.length)) * 50);

5.2 Distância (até 50 pts)

// Fórmula de Haversine para distância em km
// Se distância < service_radius:
score += Math.round(50 * (1 - dist / radius));
// Se sem geolocalização: +20 pts (benefício médio)
// Se fora do raio: 0 pts

5.3 Interpretação do Score

FaixaClassificaçãoCor
85–100ExcelenteVerde
70–84BomVerde claro
50–69RegularAmarelo
0–49BaixoCinza

6. Regras de Negócio — SuperMatch

O SuperMatch é uma funcionalidade exclusiva do plano Premium que permite ao fornecedor acessar dados completos de contato e informações privilegiadas de uma obra específica por um período limitado.

RegraDetalhe
AcessoApenas plano Premium
Duração padrão24 horas (configurável em AppConfig)
HistóricoRegistrado em SuperMatchHistory
NotificaçãoCria registro em Notification ao ativar
Expiraçãoconstruction.supermatch_expires_at controla acesso
PipelineAo encerrar, registra pipeline_status_at_close
LembretePode configurar lembrete via reminder_at

7. Fluxo de Onboarding

7.1 Etapas do Wizard

StepComponenteDados coletados
1 — Dados BásicosStepOnecompany_name, email, whatsapp, username, password
2 — MateriaisStepTwomaterials (multi-select)
3 — LocalizaçãoStepThreelocation, latitude, longitude, service_radius
4 — PlanoStepPlanplan (trial / starter / premium)

7.2 Regras Críticas do Onboarding

🚨 REGRA FUNDAMENTAL

O Supplier SEMPRE é criado com plan: "trial", independente do plano selecionado no Step 4. A ativação do plano pago ocorre exclusivamente via webhook do Stripe após confirmação de pagamento.

// Onboarding.jsx — mutationFn
const supplier = await base44.entities.Supplier.create({
  ...formData,
  plan: 'trial', // SEMPRE trial no cadastro
  trial_expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
});

// Após criar, salva supplier_id no localStorage
localStorage.setItem('supplier_id', supplier.id);

// Se plano pago → redireciona para /Checkout?plan=starter|premium
if (formData.plan !== 'trial') {
  window.location.href = createPageUrl('Checkout?plan=' + formData.plan);
}

7.3 Persistência

Durante o wizard, os dados são salvos em sessionStorage['onboarding_data'] para sobreviver a reloads. Após a criação da conta, o sessionStorage é limpo.


8. Fluxo de Pagamento (Stripe)

8.1 Diagrama do Fluxo

Frontend (/Checkout) → createCheckout [Edge Fn]

→ Stripe API: criar Checkout Session

→ Retorna URL do Stripe Checkout

Frontend → redireciona para URL Stripe

Usuário paga → Stripe processa

Stripe → POST stripeWebhook [Edge Fn]

→ Verifica assinatura HMAC

→ evento checkout.session.completed

→ Atualiza Supplier.plan para plano pago

→ Cria Notification de boas-vindas

Stripe → Redireciona para /Home?upgraded=true&plan=X

Home → exibe banner de confirmação

8.2 Proteção contra iframe

// SupplierAccount.jsx — handleCheckout()
if (window.self !== window.top) {
  alert('O checkout só funciona no app publicado.');
  return;
}
// Checkout.jsx também verifica:
if (window !== window.top) {
  setError('Acesse app.data4build.com para assinar.');
  return;
}

8.3 Metadata obrigatória na Session Stripe

metadata: {
  base44_app_id: Deno.env.get("BASE44_APP_ID"), // rastreamento Base44
  supplier_id: resolvedSupplierId,
  supplier_email: customerEmail,
  plan: 'starter' | 'premium',
  billing: 'annual' | 'monthly',
},
subscription_data: {
  metadata: {
    supplier_id, supplier_email, plan, billing
  }
}

8.4 Eventos Stripe Monitorados

EventoAção
checkout.session.completedAtualiza Supplier.plan → plano pago, limpa trial_expires_at, cria Notification
customer.subscription.deletedRebaixa Supplier.plan → "trial"

9. Funções Backend (Edge Functions)

Todas as funções são Deno Deploy handlers. Importam o SDK via npm:@base44/sdk@0.8.20.

9.1 createCheckout

CampoValor
Arquivofunctions/createCheckout.js
AutenticaçãoOpcional (app público). Tenta auth, mas aceita sem ela.
Entradaplan, billing, supplier_id, supplier_email, success_url, cancel_url
Saída{ url: string } — URL do Stripe Checkout
DependênciaStripe SDK (npm:stripe@14.21.0), STRIPE_SECRET_KEY

9.2 stripeWebhook

CampoValor
Arquivofunctions/stripeWebhook.js
AutenticaçãoVerificação HMAC via stripe.webhooks.constructEventAsync()
EntradaPayload raw do Stripe + header stripe-signature
Eventos tratadoscheckout.session.completed, customer.subscription.deleted
DependênciasSTRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
⚠️ Deno Async: Usa constructEventAsync() (não constructEvent()). Deno usa Web Crypto API assíncrona — a versão síncrona lança erro.

9.3 getSupplier

CampoValor
Arquivofunctions/getSupplier.js
AutenticaçãoNenhuma (app público). Usa asServiceRole.
Entrada{ supplier_id: string }
SaídaDados do Supplier sem o campo password_hash
UsoTrialGuard, SupplierAccount, Home — em vez de chamar entities diretamente (que falharia em app público)

9.4 authenticateSupplier

CampoValor
Arquivofunctions/authenticateSupplier.js
Entrada{ username: string, password: string }
Saída{ success, token, supplierId, company_name }
Segurança⚠️ Senha comparada em texto puro. Pendente bcrypt.
TokenBase64 simples: btoa(supplierId + ':' + timestamp). Pendente JWT.

9.5 sendWelcomeEmail

CampoValor
Arquivofunctions/sendWelcomeEmail.js
Entrada{ email: string, supplier_name: string }
ProviderBase44 SendEmail integration (usa RESEND por baixo)
Disparado porOnboarding ao criar conta

9.6 emailAutomations

CampoValor
Arquivofunctions/emailAutomations.js
AutenticaçãoRequer user.role === 'admin'
Entrada{ type: "welcome"|"day3"|"day6"|"churn48h"|"all" }
Rate limitDelay de 600ms entre envios (limite Resend 2 req/s)
FiltroApenas suppliers com plan === "trial"

Sequência de Emails por Tipo

TipoCritérioAssunto
welcomeDia 0 (criação)Bem-vindo à Data4Build! 🚀
day33 dias após cadastroVocê já explorou as oportunidades da sua região?
day66 dias após cadastro⏰ Seu teste gratuito termina amanhã
churn48hTrial expira em <48h⚠️ Menos de 48h para seu acesso expirar

9.7 notifyNewMatches

CampoValor
Arquivofunctions/notifyNewMatches.js
EntradaOpcional: { construction_ids: string[] }. Sem entrada → últimas 25h.
ThresholdNotifica supplier apenas se score ≥ 50%
AçõesCria Notification no banco + envia email HTML estilizado
AgendamentoRecomendado: diário às 8h

9.8 notifyPipelineUpdate

CampoValor
Arquivofunctions/notifyPipelineUpdate.js
TriggerAutomation de entidade (Construction update)
Aciona quandopipeline_status muda para orcamento_enviado ou negocio_fechado
AçãoPOST para PIPELINE_WEBHOOK_URL (se configurada)

9.9 generateQuotePDF

CampoValor
Arquivofunctions/generateQuotePDF.js
Entrada{ constructionId: string, supplierId?: string }
SaídaBinário PDF (Content-Type: application/pdf)
ConteúdoHeader, dados da obra, materiais, resumo financeiro, footer com data
Dependêncianpm:jspdf@2.5.1

9.10 importObrasGov

CampoValor
Arquivofunctions/importObrasGov.js
AutenticaçãoSessão admin assinada (JWT 8h) via _admin_token + isAdminAuthorized()
API Externahttps://api.obrasgov.gestao.gov.br/obrasgov/api
Parâmetrosuf, municipio, tipo, page, size, dry_run
DedupVerifica external_id antes de inserir
GeocodingNominatim (OpenStreetMap) para lat/lon por cidade
Rate limitRetry automático com delay 5s em HTTP 429

9.11 importObrasGovScheduled

Versão automática do importObrasGov. Itera por todas as 27 UFs brasileiras, até 3 páginas por UF (150 obras/UF). Executa como tarefa agendada semanal.

9.12 importCNO

Importa dados do CNO (Cadastro Nacional de Obras). Atualmente usa dados de exemplo estruturados. Limitações: sem contatos (LGPD), sem fase de obra, geolocalização ~30% incompleta.

9.13 importPNCP

Importa licitações do PNCP (Portal Nacional de Contratações Públicas). Cruza com obras CNO existentes pela cidade e materiais. Cria obras novas se não houver match.


10. Automações e Tarefas Agendadas

NomeTipoFunçãoFrequência
Importação Semanal ObrasGovScheduledimportObrasGovScheduledSemanal (recomendado: seg 3h)
Notificar Novos MatchesSchedulednotifyNewMatchesDiário (recomendado: 8h)
Pipeline Update WebhookEntity (Construction)notifyPipelineUpdateA cada update em Construction
Email Day 3 TrialScheduled / ManualemailAutomationsDiário (type: day3)
Email Day 6 TrialScheduled / ManualemailAutomationsDiário (type: day6)
Email Churn 48hScheduled / ManualemailAutomationsDiário (type: churn48h)

11. Sistema de Emails

11.1 Providers

ProviderUso
Base44 SendEmail (Resend internamente)Emails de boas-vindas, notificações de match
Resend direto via API RESTSequência de onboarding (emailAutomations)

11.2 Emails Disparados

EmailQuandoFunção
Boas-vindas HTMLAo criar contasendWelcomeEmail
Novos matchesDiariamente (novas obras)notifyNewMatches
Engajamento dia 33 dias após cadastro (trial)emailAutomations
Urgência dia 66 dias após cadastro (trial)emailAutomations
Anti-churn 48hTrial expira em <48hemailAutomations

12. Importação de Obras — Fontes de Dados

12.1 ObrasGov (Principal)

ItemDetalhe
API Basehttps://api.obrasgov.gestao.gov.br/obrasgov/api
Endpoint obras/projeto-investimento?situacao=Em+Execução&uf=SP&page=0&size=50
Endpoint % execução/execucao-fisica?idUnico=X&page=0&size=1
DedupCampo external_id com idUnico da API
GeocodingNominatim por cidade+UF
Rate limitHTTP 429 → retry automático com delay 5s

Mapeamento de Fase (% execução física)

% ExecuçãoFase mapeada
≥95% ou "concluída"entregue
75–94%acabamento
50–74%instalacoes
30–49%alvenaria
10–29%estrutura
0–9%fundacao

12.2 CNO — Cadastro Nacional de Obras

Dados distribuídos como CSV pelo Portal de Dados Abertos. Atualmente função usa dados estruturados de exemplo. Limitações: sem contatos (LGPD), fase sempre "fundação", geolocalização incompleta (~30%).

12.3 PNCP — Portal Nacional de Contratações Públicas

Licitações públicas. Função faz cruzamento com obras CNO existentes por cidade e materiais. Se não houver match, cria nova Construction com source: "pncp".


13. Secrets e Variáveis de Ambiente

SecretUsoStatus
STRIPE_SECRET_KEYCriar Checkout Sessions e verificar webhooks✅ Configurado
STRIPE_PUBLISHABLE_KEYFrontend Stripe.js (não usado atualmente)✅ Configurado
STRIPE_WEBHOOK_SECRETValidar assinatura HMAC do webhook✅ Configurado
RESEND_API_KEYemailAutomations (sequência de onboarding)✅ Configurado
TRANSPARENCIA_API_KEYPortal da Transparência (dados financeiros)✅ Configurado
BASE44_APP_IDID do app (pré-populado pelo Base44)✅ Automático
PIPELINE_WEBHOOK_URLURL para receber webhooks de pipeline update⚠️ Opcional (não obrigatório)

14. Segurança e Controles de Acesso

14.1 Controle de Acesso Frontend

ComponenteProteção
AuthGuardVerifica localStorage.supplier_id. Sem ID → redireciona para Landing.
TrialGuardChama getSupplier (serviceRole) e verifica isTrialExpired(). Se expirado → redireciona para /TrialExpirado.
AdminGuardVerifica user.role === "admin" via Base44 auth.

14.2 Controle de Acesso Backend

FunçãoControle
emailAutomationsRequer user.role === "admin"
importObrasGovRequer sessão admin assinada (isAdminAuthorized)
stripeWebhookVerificação HMAC Stripe obrigatória
getSupplierRetorna dados sem password_hash

14.3 Pendências de Segurança (Pré Go-Live)

  • 🔴 Senhas em texto puro: authenticateSupplier compara sem hash. Implementar bcrypt antes de go-live em produção.
  • 🔴 Token de sessão fraco: Token é Base64 simples. Implementar JWT com expiração.
  • 🟢 Admin token hardcoded: resolvido — todas as funções admin usam sessão assinada (isAdminAuthorized) ou token interno de rotina.
  • 🟡 Rate limiting: Sem proteção de rate limit nas Edge Functions públicas.

15. Glossário

TermoDefinição
SupplierFornecedor de materiais ou serviços cadastrado na plataforma
ConstructionObra de construção civil cadastrada no sistema
ScorePontuação 0-100 de compatibilidade entre Supplier e Construction
SuperMatchAcesso privilegiado Premium a dados completos de uma obra por 24h
PipelineFunil de vendas do fornecedor com etapas de progresso
TrialPeríodo de teste gratuito de 7 dias após o cadastro
TrialGuardComponente React que bloqueia acesso quando o trial expira
AuthGuardComponente React que bloqueia acesso sem autenticação
ObrasGovAPI pública do governo com obras federais em execução
CNOCadastro Nacional de Obras — base LGPD do governo
PNCPPortal Nacional de Contratações Públicas — licitações abertas
NominatimServiço de geocoding do OpenStreetMap (gratuito)
asServiceRolePermissão elevada do SDK Base44 para operações admin sem auth de usuário
external_idID da fonte externa (ObrasGov, CNO) para evitar duplicatas
data_quality_scoreScore 0-100 da completude dos dados de uma obra

⚡ Data4Build — Documentação Técnica

Versão 1.0 · Gerado em 17 de novembro de 2026 · Confidencial

Para atualizar este documento, acesse /Documentacao no app e use o botão de impressão para gerar PDF.