Todos os cases
~/cases/crm-eleitoral-dimas-gadelha
Sistemas internosCâmara e Assembleiaabr 2026 → ago 2026Em produção

P-12

CRM Eleitoral Dimas Gadelha

Pesquisa de campo, atendimento e relacionamento num só sistema, com a permissão decidida no banco.

clienteGabinete do deputado estadual Dimas Gadelha

Plataforma do gabinete do deputado estadual Dimas Gadelha que reúne site público, formulários de rua, área de voluntários e painel de gestão. Fichas de pesquisa de campo são pontuadas e classificadas automaticamente no Postgres, acompanhadas por território e equipe e resumidas num relatório executivo em PDF. Roda em Cloudflare Workers com Supabase, RLS em todas as 18 tabelas e um papel de acesso mínimo que emite o relatório sem enxergar nenhuma ficha.

18/18
tabelas com RLS
39 de 46
funções SECURITY DEFINER
52
policies criadas
62
migrations SQL
  • cloudflare
  • supabase
  • postgres
  • rls
  • lgpd
  • react
architecture.pt.svgampliar ↓

01Visão geral

O CRM Eleitoral Dimas Gadelha é a plataforma digital do gabinete do deputado estadual Dimas Gadelha. Ela junta, num só sistema, o site público, os formulários que as equipes usam na rua, uma área para voluntários e um painel de gestão para a coordenação. Cada pessoa que entra em contato com o gabinete, seja pelo site, num atendimento itinerante num bairro ou numa entrevista de pesquisa, vira um registro organizado, com origem, território e histórico.

O ponto central é a pesquisa de campo. Entrevistadores preenchem uma ficha padronizada no celular; o banco calcula sozinho uma pontuação para cada ficha e a classifica em faixas configuráveis; a coordenação acompanha tudo por bairro, município e equipe, e emite um relatório executivo em PDF com um clique.

02O problema

  • Contatos espalhados. Cadastros do site, listas de atendimento de rua e uma base institucional antiga viviam em lugares diferentes, sem deduplicação.
  • Pesquisa de campo em papel ou planilha. Sem padrão de perguntas, sem classificação e sem como cruzar respostas com território ou com a equipe que entrevistou.
  • Dados pessoais sensíveis. Opinião política, religião e telefone de cidadãos: exige LGPD levada a sério, prova de consentimento e acesso mínimo por papel.
  • Públicos com níveis de confiança muito diferentes. Formulários abertos a qualquer um, voluntários autenticados, coordenação com acesso total e pessoas que só precisam ver um relatório agregado.

03A solução

  • Site público e cadastro de apoiadores em etapas, com link de indicação por voluntário.
  • Atendimento itinerante: formulário de rua que reconhece o telefone em tempo real, mostra se é a 1ª ou a N-ésima visita e aceita data retroativa para digitar fichas de papel. Um perfil por telefone normalizado, uma linha por visita.
  • Ficha de abordagem (pesquisa de campo): questionário padronizado com bloco de equipe (coordenador e entrevistador), cidade com lista oficial de municípios e bairro com autocompletar, aceite LGPD versionado.
  • Pontuação automática: pesos por resposta, faixas de classificação e perfil do entrevistador configuráveis pela coordenação, com versão e auditoria de cada alteração.
  • Painel da coordenação: KPIs e gráficos, tabela de registros com busca e filtros por faixa, bairro e equipe (multi-seleção), exportação CSV que respeita os filtros, mapa de calor com clusterização, mapa coroplético por município e bairro cruzado com a classificação, aniversariantes, aprovação de voluntários e gestão de papéis.
  • Relatório executivo em PDF, gerado no navegador, disponível no painel e numa rota dedicada para um papel de acesso mínimo.
  • Área do voluntário: painel pessoal, ranking, níveis por número de indicados e materiais de divulgação.
  • RLS habilitada nas 18 tabelas; papéis em tabela própria, checados por has_role com EXECUTE revogado de anon.
  • Papel 'relatorio' sem nenhuma policy de leitura: o PDF sai de uma RPC SECURITY DEFINER com recorte de colunas e telefone mascarado.
  • Pontuação de fichas calculada por trigger, com configuração versionada e auditoria de antes e depois.
  • Aceite LGPD exigido em três camadas (Zod, servidor e CHECK no banco), com versão do termo gravada.
  • Cliente service_role confinado a arquivos .server.ts ou import dinâmico dentro do handler.
  • Agregações do painel e do mapa territorial feitas no Postgres, não no navegador.

04Arquitetura

arquitetura real · passe o cursor nos nós
Ler o diagrama como lista (18 componentes, 21 conexões)

Componentes

  • Clientes: Público<br>landing · cadastro, Equipes de campo<br>fichas de abordagem<br>atendimento itinerante, Voluntários<br>área logada · ranking, Coordenação<br>painel admin, Papel relatorio<br>só emite o PDF
  • Cloudflare Workers: TanStack Start · SSR<br>React 19, createServerFn<br>Zod em toda entrada, requireSupabaseAuth<br>JWT via getClaims
  • Postgres: 18 tabelas<br>RLS em todas, 39 funções SECURITY DEFINER<br>has_role · agregações, Pontuação versionada<br>trigger + auditoria
  • Supabase: Auth<br>e-mail/senha + OAuth, PostgREST<br>chave publishable, 7 Edge Functions<br>aprovação · e-mail · conta, PG

Conexões

  • Público<br>landing · cadastro → TanStack Start · SSR<br>React 19
  • Equipes de campo<br>fichas de abordagem<br>atendimento itinerante → TanStack Start · SSR<br>React 19
  • Voluntários<br>área logada · ranking → TanStack Start · SSR<br>React 19
  • Coordenação<br>painel admin → TanStack Start · SSR<br>React 19
  • Papel relatorio<br>só emite o PDF → TanStack Start · SSR<br>React 19
  • TanStack Start · SSR<br>React 19 → createServerFn<br>Zod em toda entrada
  • createServerFn<br>Zod em toda entrada → 18 tabelas<br>RLS em todas (forms públicos<br>service_role só no servidor)
  • createServerFn<br>Zod em toda entrada → requireSupabaseAuth<br>JWT via getClaims
  • requireSupabaseAuth<br>JWT via getClaims → PostgREST<br>chave publishable (token do usuário)
  • Voluntários<br>área logada · ranking → Auth<br>e-mail/senha + OAuth
  • Coordenação<br>painel admin → Auth<br>e-mail/senha + OAuth
  • Papel relatorio<br>só emite o PDF → Auth<br>e-mail/senha + OAuth
  • PostgREST<br>chave publishable → 18 tabelas<br>RLS em todas
  • PostgREST<br>chave publishable → 39 funções SECURITY DEFINER<br>has_role · agregações
  • 39 funções SECURITY DEFINER<br>has_role · agregações → Pontuação versionada<br>trigger + auditoria
  • 7 Edge Functions<br>aprovação · e-mail · conta → Auth<br>e-mail/senha + OAuth
  • 7 Edge Functions<br>aprovação · e-mail · conta → Resend<br>e-mail transacional
  • Coordenação<br>painel admin → IBGE<br>malhas e municípios
  • createServerFn<br>Zod em toda entrada → Nominatim / OSM<br>geocoding com cache
  • Papel relatorio<br>só emite o PDF → jsPDF<br>relatório no navegador
  • Coordenação<br>painel admin → jsPDF<br>relatório no navegador

Uma única aplicação TanStack Start roda em Cloudflare Workers, com SSR e funções de servidor tipadas (createServerFn) que o cliente chama como RPC. Toda lógica nova de backend fica nessas funções; as Edge Functions do Supabase ficaram restritas ao fluxo legado de aprovação de voluntários, redefinição de senha e e-mail. O Postgres é a fonte de verdade de permissão: papéis numa tabela separada, checados por uma função has_role dentro das policies e das RPCs.

05Por dentro

Backend e dados
  • 62 migrations SQL versionadas, 18 tabelas em public, 3 views e 46 funções PL/pgSQL/SQL (39 delas SECURITY DEFINER, com search_path fixo).
  • Convenção .functions.ts / .server.ts: o arquivo .functions.ts exporta a função de servidor e pode ser importado pelo cliente; a implementação com o cliente service_role fica em .server.ts ou é importada dinamicamente dentro do handler, para nunca entrar no bundle do navegador. São 13 funções de servidor.
  • Atendimento itinerante: a RPC gi_register_visit faz o upsert do perfil (único por telefone normalizado) e insere a visita numa transação, devolvendo se é perfil novo e o total de visitas. Se o perfil é novo e o telefone não existe na base geral, o servidor cria também o apoiador.
  • Pontuação de fichas: o modelo vive em tabelas (pontuacao_pergunta, pontuacao_opcao, pontuacao_faixa). Um trigger AFTER INSERT em leads_abordagem calcula a pontuação; salvar a configuração gera uma nova versão e uma linha de auditoria com o estado antes e depois e quem alterou; pontuacao_recalcular reprocessa a base. A view leads_abordagem_scored entrega fichas já com pontuação, faixa e flag de pendência.
  • Agregação no servidor: dashboard, mapa territorial, analytics e aniversariantes são RPCs que devolvem JSON agregado, em vez de trazer linhas para o navegador.
  • Teto de 1.000 linhas do PostgREST: um helper fetchAllRange pagina por .range() com ordenação determinística e um limite de segurança de 200 mil linhas, usado em exportações e seleções em massa.
  • Normalização no banco: triggers normalizam município e UF em apoiadores e contatos; telefones são comparados só por dígitos.
Frontend
  • TanStack Start + React 19, roteamento por arquivos (28 arquivos de rota: 13 páginas públicas, login admin, layout protegido e 12 telas do painel).
  • TanStack Query com ensureQueryData no loader e useSuspenseQuery no componente; nada de useEffect + fetch para carga inicial.
  • Tailwind CSS 4 com tokens de tema em CSS, shadcn/ui + Radix (47 componentes base), React Hook Form + Zod com os mesmos esquemas no cliente e no servidor.
  • Mapas: Leaflet com markercluster e heatmap; mapa coroplético com a malha oficial de municípios do IBGE.
  • Relatório PDF com jsPDF e jspdf-autotable, gerado inteiramente no navegador a partir de uma RPC com recorte de colunas: tabela diária, distribuição por faixa, equipe e participação presencial × remota, sempre no fuso de Brasília.
  • Cerca de 30 mil linhas de TypeScript/TSX (excluindo arquivos gerados).
Infraestrutura e deploy
  • Cloudflare Workers com nodejs_compat, configurado por wrangler.jsonc e o plugin Vite da Cloudflare.
  • Deploy pela plataforma Lovable, conectada ao branch principal; o fluxo é alterar, validar com build de produção e enviar.
  • Supabase para Postgres, Auth, Storage (bucket de materiais de divulgação) e Edge Functions em Deno.
  • Resend para e-mails transacionais (aprovação de voluntário, redefinição de senha).
  • Variáveis de servidor (SUPABASE_SERVICE_ROLE_KEY, RESEND_API_KEY) só como segredo de ambiente; o cliente recebe apenas URL e chave publishable.

06Segurança

7 ataques considerados, 7 defesas em produção.

ataquedefesa
Atalho pela API

Pular a interface e falar direto com o banco ou a API, com a chave pública na mão.

  • Ler dados de cidadãos chamando a API direto com a chave pública

    RLS nas 18 tabelas; leitura de apoiadores e contatos só para admin, ou o voluntário vendo o próprio registro e indicados

  • Chamar funções internas e agregações via RPC

    EXECUTE revogado de PUBLIC e anon nas funções internas; agregações abortam com FORBIDDEN sem papel admin

Escalada de privilégio

Quem tem algum acesso tentando ganhar mais: virar admin, ler o que não deve, manter acesso revogado.

  • Conceder a si mesmo o papel de administrador

    Papéis em user_roles, inserção só por quem já é admin via has_role, função com EXECUTE revogado de anon

  • Usar a conta de relatório para extrair fichas individuais

    O papel não tem policy de SELECT; só uma RPC SECURITY DEFINER com recorte de colunas, sem nome e com telefone mascarado

Vazamento e rastreio de dados

Enumerar quem está na base, raspar dados pessoais, ligar perguntas a pessoas, extrair segredos.

  • Extrair a chave service_role do bundle do navegador

    Cliente privilegiado só em .server.ts ou import dinâmico no handler; funções admin validam o JWT e o papel antes de usá-lo

Adulteração e rastro

Mexer em contagens, apagar a base, editar o histórico ou negar o que foi autorizado.

  • Gravar ficha de pesquisa sem consentimento forjando a requisição

    Zod só aceita true, o servidor repete a regra e um CHECK no banco recusa a ficha; data e versão do termo são gravadas

  • Alterar pesos da classificação sem deixar rastro

    Cada gravação gera nova versão e auditoria com antes, depois e autor; cada resultado guarda a versão que o produziu

Autorização no banco, não na tela. As 18 tabelas têm RLS habilitada. Papéis (admin, ativista, relatorio) ficam em user_roles, nunca no perfil, e são checados por has_role(uid, role), uma função SECURITY DEFINER cuja execução foi revogada de anon e PUBLIC. O layout do painel faz um gate de sessão e papel, mas é só experiência: quem tentar chamar a API direto com a chave pública esbarra nas policies.

Policies mínimas. Leitura de apoiadores só para administradores, ou para o voluntário ver o próprio registro e quem ele indicou. A base institucional de contatos tem acesso exclusivo de administrador. Escrita de papéis só por administrador, e uma policy impede que um administrador remova o próprio papel de admin. Uma policy permissiva de leitura (USING (true)) criada no início foi identificada e removida por migration, com a tela de confirmação passando a usar uma RPC que devolve só os campos necessários.

Funções fechadas por padrão. Funções de trigger e internas tiveram EXECUTE revogado de PUBLIC, anon e authenticated (incluindo um bloco que revoga em lote). As RPCs de agregação abrem com IF NOT has_role(auth.uid(), 'admin') THEN RAISE EXCEPTION 'FORBIDDEN'.

Papel de acesso mínimo para relatório. Uma conta com o papel relatorio entra e é levada a uma página com um único botão. Ela não tem policy de leitura em leads_abordagem; o dado vem de leads_abordagem_relatorio_rows(), SECURITY DEFINER, que só aceita admin ou relatorio e devolve um recorte sem nome, telefone ou campos abertos. O telefone vira apenas um marcador de presença (******), porque o relatório só conta quantas fichas têm contato.

Service role confinada. O cliente service_role só é importado em arquivos .server.ts ou dinamicamente dentro do handler. As funções de servidor administrativas passam pelo middleware requireSupabaseAuth, que valida o JWT com getClaims, e depois por uma checagem explícita de papel antes de usar o cliente privilegiado. Uma falha desse tipo no mapa administrativo foi corrigida em maio de 2026.

LGPD. A ficha de pesquisa exige aceite do termo em três camadas: o esquema Zod só aceita true, a função de servidor repete a regra e um CHECK no banco recusa ficha da versão atual sem aceite. O aceite grava data e versão do texto do termo, para que mudar a redação não invalide consentimentos já coletados; fichas antigas não são marcadas retroativamente como aceitas. O voluntário pode excluir a própria conta por uma função de servidor dedicada.

Validação de entrada. Todas as funções de servidor validam com Zod (tamanhos máximos, enums fechados, arrays com limite). Datas de campo no futuro ou com mais de 90 dias são recusadas no servidor, no fuso de Brasília. O login administrativo tem honeypot, limites de tamanho e, como atrito adicional à limitação nativa do Supabase Auth, bloqueio de 15 minutos após 5 falhas com backoff exponencial no cliente.

Higiene. Rotas do painel, do formulário de campo e do relatório marcadas como noindex. Nenhuma chave de servidor no bundle; Google OAuth passa por um broker gerenciado em vez de expor configuração de provedor no cliente.

07Desafios técnicos

Dar acesso a um relatório sem dar acesso aos dados

O pedido era simples: uma pessoa precisa emitir o relatório, mas não pode ver fichas. Em vez de criar policies de leitura parciais, que vazariam por qualquer consulta bem montada, a solução foi um papel sem nenhuma policy de SELECT e uma RPC SECURITY DEFINER que devolve exatamente as colunas que o relatório usa, espelhando a lista definida no código do PDF. O telefone é substituído por um marcador de presença ainda no banco.

Pontuação configurável sem perder rastreabilidade

A coordenação queria ajustar pesos e faixas ao longo da campanha. O modelo foi para tabelas, o cálculo para um trigger e cada gravação de configuração passou a gerar uma versão e uma auditoria com antes e depois. Cada resultado guarda a versão de configuração que o produziu, e um recálculo reprocessa a base inteira quando a regra muda.

Mudar o formulário oficial com fichas já coletadas

A versão 2 da ficha trocou perguntas e acrescentou o aceite LGPD. A migration adicionou form_versao com CHECK aplicado como NOT VALID e validado em seguida, a obrigatoriedade do aceite só para a versão 2, e o servidor grava a versão explicitamente para que um cliente com bundle antigo não seja registrado como formulário novo. Painel, pontuação e RPCs passaram a tratar as duas versões.

Perfis únicos por telefone em atendimentos repetidos

A mesma pessoa aparece em vários atendimentos, às vezes digitados dias depois. A RPC gi_register_visit normaliza o telefone, faz upsert do perfil, insere a visita com data retroativa opcional e devolve o número da visita, mantendo primeiro e último atendimento coerentes. O formulário consulta o telefone em tempo real para avisar a equipe antes de enviar.

08Resultados

  • 736 commits entre abril e agosto de 2026; 62 migrations; 18 tabelas com RLS; 52 policies criadas.
  • Pesquisa de campo saiu do papel para uma ficha padronizada com classificação automática e relatório executivo de um clique.
736
commits
como medimos

git rev-list --count HEAD

62
migrations SQL
como medimos

ls supabase/migrations | wc -l

18/18
tabelas com RLS
como medimos

grep de CREATE TABLE e ENABLE ROW LEVEL SECURITY nas migrations

52
policies criadas
como medimos

grep -ic 'create policy' nas migrations (5 DROP POLICY posteriores)

39 de 46
funções SECURITY DEFINER
como medimos

script sobre as migrations: nomes distintos de CREATE FUNCTION com SECURITY DEFINER no cabeçalho

13
server functions
como medimos

grep -c 'createServerFn(' em src/lib/*.functions.ts e src/utils/*.functions.ts

7
edge functions
como medimos

ls supabase/functions (excluindo _shared)

~29,9 mil
linhas TS/TSX
como medimos

wc -l em git ls-files *.ts *.tsx, excluindo routeTree.gen.ts e types.ts gerados

5.080
linhas SQL
como medimos

cat supabase/migrations/*.sql | wc -l

09Linha do tempo

  1. 27 abr 2026

    Base do app, tabela de apoiadores e endurecimento de RLS, removendo uma policy de leitura permissiva

  2. abr 2026

    29–30/04: área do voluntário com indicação e ranking; base institucional de contatos com acesso só de admin

  3. mai 2026

    12–15/05: formulário de rua, analytics e mapa com clusterização e cache de geocoding

  4. jun 2026

    02–08/06: atendimento itinerante com perfil único por telefone, histórico de visitas e data retroativa

  5. 07 jul 2026

    Ficha de pesquisa de campo, pontuação automática versionada e mapa territorial coroplético

  6. jul 2026

    21–30/07: relatório executivo em PDF e papel de acesso mínimo para emiti-lo

  7. 15 ago 2026

    Versão oficial da ficha com consentimento LGPD exigido no banco

10Stack

Frontend
  • React 19
  • TanStack Start
  • TanStack Router
  • TanStack Query
  • TypeScript
  • Tailwind CSS 4
  • shadcn/ui
  • Radix
  • React Hook Form
  • Recharts
  • Leaflet
  • jsPDF
Backend
  • TanStack Start server functions
  • Cloudflare Workers
  • Supabase Auth
  • Supabase Edge Functions (Deno)
  • PL/pgSQL
  • Resend
Dados
  • PostgreSQL
  • Row Level Security
  • Triggers e views
  • pg_trgm
  • Supabase Storage
Infra
  • Cloudflare Workers
  • Vite 7
  • Lovable
  • Supabase CLI
  • Bun
Segurança
  • RLS em todas as tabelas
  • Papéis com has_role SECURITY DEFINER
  • Zod em toda entrada
  • Consentimento LGPD com CHECK
  • Honeypot
  • service_role só no servidor

11Ficha técnica

node@crm-eleitoral-dimas-gadelha: ~/cases/crm-eleitoral-dimas-gadelha
node@crm-eleitoral-dimas-gadelha ─────────────
type
plataforma de gabinete · civic tech
stack
TanStack Start · React 19 · TS
db
Postgres · 18 tabelas · RLS 18/18
auth
Supabase Auth · 3 papéis via has_role
deploy
Cloudflare Workers
modules
campo · atendimento · voluntários · painel · relatório
status
produção
$ ls supabase/migrations | wc -l
62
$ grep -h 'ENABLE ROW LEVEL SECURITY' supabase/migrations/*.sql | sort -u | wc -l
18 # 18 tabelas, 18 com RLS
$ psql -c "select public.leads_abordagem_relatorio_rows();" # como usuário sem papel
ERROR: FORBIDDEN
$ psql -c "insert into leads_abordagem (form_versao, nome_abordado, lgpd_aceite) values (2, 'Teste', false);"
ERROR: new row for relation "leads_abordagem" violates check constraint "leads_abordagem_lgpd_v2_chk"
$ git log --oneline | wc -l
736
NODE

TECNOLOGIA E INTELIGÊNCIA POLÍTICA

© 2026 NODE. Todos os direitos reservados.