Cada decisão da Fase 1, virando tabela

Quatro princípios organizam todas as tabelas abaixo, todos derivados diretamente da Fase 1:

leads é o centro do modelo — praticamente toda outra tabela existe para descrever, pontuar, rastrear ou logar um lead. As linhas tracejadas indicam referência lógica (não é uma chave estrangeira do banco); todas as demais são FKs reais, com detalhe completo na tabela de relacionamentos abaixo.

Suporta a rotina diária (seção 8 da Fase 1) e a auditoria (seção 12) — todo evento relevante precisa de um "quem". Três papéis: colaborador (pesquisa, contata, atualiza leads), gestor (valida amostralmente células territoriais, decide duplicatas nível 3), admin (única exceção com permissão de alterar log de auditoria — e essa exceção também fica registrada).

Cada célula (bairro na Capital, município a partir da Grande SP) carrega o critério composto de cobertura aprovado: termos_distintos_count, fontes_cruzadas[] e rodadas_sem_novo_lead juntos determinam quando o status avança para mapeado. A tabela termos_busca_executados é o registro de apoio — cada termo de busca realmente executado numa célula vira uma linha ali, o que sustenta o critério sem depender de estimativa manual.

A tabela mais importante do schema. Três decisões merecem destaque:

Funil e status de contato são colunas separadas

Exatamente como aprovado na seção 9: funil_estagio é o enum linear de 8 estágios (colunas do Kanban); status_contato é um enum paralelo e opcional, que só passa a fazer sentido a partir de "em_contato" — um card pode oscilar entre "sem resposta" e "retorno solicitado" sem nunca mudar de coluna.

Corte de "grande rede" é regra codificada, não julgamento

Os campos numero_unidades e numero_estados alimentam a coluna booleana excluido_grande_rede: verdadeira quando >20 lojas OU presença em >3 estados, exatamente o corte aprovado na seção 1. Entre 6 e 20 lojas o lead entra normalmente, mas o Lead Score (próxima seção) já reflete o porte maior nos critérios de fit.

Exclusão sempre com motivo

Um check constraint impede fisicamente que um lead vire classe = 'X' sem motivo_exclusao preenchido — testado durante a validação deste schema: a tentativa de gravar uma exclusão sem motivo foi rejeitada pelo banco, como pretendido pela seção 2 ("esses registros não desaparecem — ficam com status Excluído e o motivo").

lead_campo_fonte guarda, para qualquer campo do lead, o valor encontrado, se é confirmado ou estimado, a fonte pública (descrição + URL quando existir) e quem pesquisou. Isso resolve dois requisitos da Fase 1 ao mesmo tempo: "Não localizado" nunca é confundido com "ninguém pesquisou ainda" (a ausência de linha aqui é o segundo caso; um valor explícito é o primeiro), e nenhuma estimativa aparece disfarçada de fato confirmado.

Os 4 blocos ponderados (A–D, até 100 pontos) vivem em pesos_lead_score, versionados. Cada cálculo de score gera uma linha em lead_score_historico com os 4 blocos, os redutores e o score_total como coluna GENERATED (calculada pelo próprio banco, nunca pode ficar dessincronizada da soma real) — e referencia qual versao_pesos foi usada.

O campo lead_score em leads é o valor corrente cacheado (para ordenar a fila de contato sem precisar agregar histórico toda hora); o trigger de auditoria grava automaticamente todo recálculo — testado: alterar lead_score de um lead gerou, na validação deste schema, uma linha com ação score_recalculado sem nenhuma ação extra da aplicação.

Os "portões de exclusão" (empresa encerrada, fabricante/distribuidor, grande rede acima do corte, duplicata) não pontuam — chegam direto a classe = 'X' sem passar pelos blocos A–D.

Só o nível 3 do checklist de dedup (nome muito similar + endereço próximo) precisa de tabela própria — é o único que exige decisão humana obrigatória. Níveis 1 (CNPJ/telefone idênticos) e 2 (mesmo domínio/@Instagram) mesclam automaticamente: o lead duplicado recebe duplicata_de apontando para o registro original, e o evento fica em eventos_auditoria, sem gerar linha em duplicatas_candidatas.

duplicatas_candidatas guarda o par (lead_id_a, lead_id_b), o nível de confiança e a decisão (mesclado / rejeitado) de quem revisou — nunca apaga nenhum dos dois registros, só decide qual vira o principal.

Todo contato (WhatsApp, ligação, e-mail, visita) vira uma linha em interacoes, com resumo, o status de contato resultante e a próxima ação com data. Isso é o que alimenta o checklist de fechamento do dia da rotina diária: nenhuma interação registrada hoje deve ficar sem proxima_acao_em definida.

eventos_auditoria é insert-only por desenho: nenhuma coluna de "editado_em" nem trigger de update — a única forma de "corrigir" um evento é inserir um novo evento que explique a correção. Um trigger genérico (fn_log_mudanca_lead) grava automaticamente toda mudança de funil_estagio, status_contato, classe e lead_score, com valor anterior e novo — testado com uma sequência real de insert + updates antes deste documento ser escrito, confirmando que o log é gerado sem qualquer chamada extra da aplicação.

A restrição de que só admin pode alterar ou apagar uma linha de log é reforçada com REVOKE UPDATE, DELETE no papel de conexão da aplicação — depende do usuário de banco de cada ambiente (dev/staging/produção), por isso fica documentada no schema mas aplicada na configuração de cada ambiente, não como constraint fixa.

• Enums exigem migração para crescer — adicionar um novo tipo_estabelecimento ou funil_estagio no futuro é uma migração de schema (ALTER TYPE ... ADD VALUE), não uma configuração de aplicação. Aceitável agora porque esses valores vieram de decisão explícita da Fase 1, mas vale saber que não são "livres".
• lead_campo_fonte pode crescer rápido — cada campo rastreável de cada lead gera uma linha. Para o volume de milhares de empresas citado no briefing, isso é tranquilo para o Postgres, mas indexação por (lead_id, campo) já foi incluída para manter consulta rápida.
• Trigger de auditoria cobre hoje só leads — celulas_territoriais e outras tabelas podem reusar a mesma função com pequena adaptação quando a Fase 3/4 definir quais mudanças nelas também precisam de log automático.
• Reciclagem de células depende de job agendado — o schema prepara o índice, mas o agendamento (cron/worker) é decisão de infraestrutura da Fase 4, fora do escopo de banco de dados.

Com o banco definido e testado, a Fase 3 — Telas do app/CRM desenha a interface sobre estas tabelas: Kanban do funil, ficha do lead com histórico de proveniência e interações, painel de células territoriais e fila de contato priorizada por classe. Nenhuma decisão de schema fica pendente de aprovação — o desenho de tela pode começar diretamente.