Todos los casos
~/cases/pimenta-no-senado
Plataformas y CRMMayoritarias estatalesdic 2025 → sep 2026Completado

P-13

Pimenta no Senado

Registros, activistas y CRM en una base: un perfil por persona y puntuación controlada por Postgres.

clienteCampaña a nivel estatal

Plataforma de campaña estatal con tres frentes: páginas de registro, panel de activistas con recomendaciones y clasificaciones, y CRM administrativo. Unifica perfiles por teléfono, calcula Lead Score y ofrece embudo UTM y mapa geográfico. Usa Supabase con 38 Edge Functions y 221 migraciones, RLS en cada tabla, Turnstile y límites en el inicio de sesión, registro público solo por función de servidor y protección contra borrados masivos.

221
Migraciones
38
funciones de borde
67
cuadros
~53k
Líneas TS/TSX
  • supabase
  • postgres
  • rls
  • edge
  • react
  • crm
  • anti-bot
  • rate-limiting
  • lgpd
  • pwa
architecture.es.svgampliar ↓

01Sinopsis

Pimenta no Senado es la plataforma digital de una campaña electoral en todo el estado. Reúne tres cosas que generalmente viven en herramientas separadas: las páginas públicas donde las personas se registran como seguidores, un panel de control para que los voluntarios (los "activistas") sigan a quién trajeron y vean cómo se clasifican, y un CRM interno donde el equipo de coordinación ve toda la base, lo segmenta, envía correo electrónico y medidas de dónde vino cada registro.

En la práctica, un ciudadano llega a través de una landing page o un enlace de referencia, rellena un formulario corto y se convierte en un miembro de la comunidad. Perfil único tecleado por el número de teléfono, incluso si se registraron en cinco páginas diferentes durante varios meses. Cada acción que realizan añade puntos a Puntuación de plomo, que el equipo usa para saber quién está frío, caliente o listo para pedir más.

El sistema funcionó en producción desde diciembre 2025 hasta septiembre 2026, pasó por más de 1,800 y migraciones de bases de datos 221, y manejó los datos personales de los votantes bajo la ley de protección de datos de Brasil (LGPD), en un entorno donde la audiencia incluye oponentes.

02El problema

  • Registros dispersos. La misma persona apareció en supporters, en tablas de páginas de destino por campaña, en formularios de eventos y en una base heredada importada. Nadie podría responder "cuántas personas reales tenemos" o "qué ha hecho esta persona con nosotros".
  • Reconocimiento. El equipo necesitaba saber qué página, qué UTM y qué activista trajeron cada registro, y para contar referencias de partidarios aparte de la contratación de new-activist.
  • Compromiso medible. Las acciones (registro, referencia, asistencia, interacciones externas por correo electrónico y WhatsApp) tenían que convertirse en una puntuación configurable, sin hojas de cálculo.
  • Exposición. Las formas públicas atraen a los bots, el área activista pone una superficie autenticada frente a miles de personas fuera del personal, y la base de datos contiene los nombres de los votantes, teléfonos y correos electrónicos.

03La solución

Captura pública

  • Formulario de página de destino Multi-step más un formulario ligero con un paso three-way post-signup (compartir, convertirse en activista, unirse al canal oficial).
  • Páginas de página de destino temáticas registradas en landing_pages, cada uno con sus propios puntos registro y causa.
  • Campo de la ciudad como un combobox sobre la lista de municipios de la oficina nacional de estadísticas (hoja inferior en el móvil).
  • PWA instalable, widget de accesibilidad, banner de consentimiento y política de privacidad.

Área de Activistas

  • Enlace de referencia personal con código QR, plantillas de mensajes y materiales descargables.
  • Rankings generales, regionales y de ciudades, niveles, logros y una racha diaria.
  • Visibilidad restringida: a través de RLS, un activista solo puede leer su propio registro y los partidarios a los que se refirió.

Admin CRM

  • Perfil único por número de teléfono, con un viaje (un evento por página registro), historia field-by-field, puntuación y banda, filtros por etiqueta, origen, estado y banda, y exportación de CSV.
  • Puntuación de plomo con acciones, bandas y causas configurables; puntos automáticos en registro y referencia; importación de CSV limitada a acciones externas.
  • Rastreador: orígenes, un constructor de cinco dimensiones UTM y un embudo conversion/abandono por página y por UTM.
  • Panel de control con KPI, un coroplético de país con drill-down en el estado de prioridad y un filtro de origen; una tarjeta que falla no quita la página.
  • Cola de aprobación de activistas, invitaciones individuales y masivas, password-link reenviar.
  • Email marketing con plantillas, programación y métricas sincronizadas desde el proveedor.
  • Clasificación de referencias con una curva de Pareto, eventos, peticiones, un carrusel de noticias e informes PDF.
  • Modo de privacidad: un botón de cabecera enmascara nombres, teléfonos y figuras en la pantalla, por lo que el panel de control se puede mostrar en reuniones o grabaciones de pantalla.
  • Un único perfil identificado por teléfono en la parte superior de varias tablas registro, con una función de ingestión compartida por los disparadores en tiempo real y un relleno por lotes idempotente 20,000-fila.
  • Puntuación de clientes potenciales idempotente: dos índices únicos parciales mantienen el dedup automatic-event (por fuente) aparte del dedup CSV-import (por día).
  • registro público solo a través de una función Edge: INSERT anónimo revocado, Turnstile verificado del lado del servidor y una lista blanca de columnas.
  • Inicie sesión con Turnstile y un límite de velocidad two-key (5 fallas por IP, 8 por correo electrónico en 2 min), con IP almacenadas solo como hashes.
  • Después de un incidente mass-deletion, las filas se restauraron desde el registro de auditoría y un desencadenador a nivel de sentencia que rechaza cualquier DELETE sobre las filas 5.
  • El reenvío a sistemas externos pasó del navegador a un desencadenador pg_net con su clave en Vault.

04Arquitectura

arquitectura real · pasa el cursor por los nodos
Leer el diagrama como lista (23 componentes, 23 conexiones)

Componentes

  • Clientes: Simpatizante<br>(página de destino, páginas temáticas, PWA), Activista<br>(/ativista · clasificación, enlace, QR), Coordinación<br>(/admin · CRM)
  • React 18 + Vite SPA: Turnstile<br>registro e inicio de sesión, tracking.ts<br>UTM + embudo, Modo de privacidad<br>ocultación de datos en el cliente
  • Funciones de borde 38 (Deno): submit-form<br>Turnstile + lista blanca, inicio de sesión<br>Turnstile + límite de tarifa, alta / activación<br>enlace HMAC uid+sig, funciones de administración<br>JWT + is_admin(), webhooks<br>secreto / Svix
  • Postgres: RLS en public.*<br>user_roles + has_role(), CRM de movilización<br>crm_ingest · perfil identificado por teléfono, Puntuación de plomo<br>eventos idempotentes, Controles de protección<br>registro de auditoría + bloqueo de DELETE masivo, pg_net + bóveda<br>reenvío desde el servidor, pg_cron<br>limpieza de registros
  • Supabase: EF, Auth<br>correo y contraseña, PostgREST<br>SECURITY DEFINER RPCs, PG

Conexiones

  • Simpatizante<br>(página de destino, páginas temáticas, PWA) → Turnstile<br>registro e inicio de sesión
  • Turnstile<br>registro e inicio de sesión → submit-form<br>Turnstile + lista blanca
  • Activista<br>(/ativista · clasificación, enlace, QR) → inicio de sesión<br>Turnstile + límite de tarifa
  • Coordinación<br>(/admin · CRM) → inicio de sesión<br>Turnstile + límite de tarifa
  • inicio de sesión<br>Turnstile + límite de tarifa → Auth<br>correo y contraseña
  • Activista<br>(/ativista · clasificación, enlace, QR) → PostgREST<br>SECURITY DEFINER RPCs
  • Coordinación<br>(/admin · CRM) → PostgREST<br>SECURITY DEFINER RPCs
  • Coordinación<br>(/admin · CRM) → funciones de administración<br>JWT + is_admin()
  • tracking.ts<br>UTM + embudo → PostgREST<br>SECURITY DEFINER RPCs
  • submit-form<br>Turnstile + lista blanca → PG
  • PostgREST<br>SECURITY DEFINER RPCs → RLS en public.*<br>user_roles + has_role()
  • RLS en public.*<br>user_roles + has_role() → CRM de movilización<br>crm_ingest · perfil identificado por teléfono
  • CRM de movilización<br>crm_ingest · perfil identificado por teléfono → Puntuación de plomo<br>eventos idempotentes
  • alta / activación<br>enlace HMAC uid+sig → Auth<br>correo y contraseña
  • alta / activación<br>enlace HMAC uid+sig → Resend<br>correo transaccional y campañas
  • funciones de administración<br>JWT + is_admin() → Resend<br>correo transaccional y campañas
  • funciones de administración<br>JWT + is_admin() → GA4<br>Datos API
  • webhooks<br>secreto / Svix → PG
  • N8N / WhatsApp<br>webhooks → webhooks<br>secreto / Svix
  • Resend<br>correo transaccional y campañas → webhooks<br>secreto / Svix
  • pg_net + bóveda<br>reenvío desde el servidor → N8N / WhatsApp<br>webhooks
  • submit-form<br>Turnstile + lista blanca → Cloudflare<br>Turnstile siteverify
  • inicio de sesión<br>Turnstile + límite de tarifa → Cloudflare<br>Turnstile siteverify

El SPA habla con Supabase de dos maneras: lecturas autenticadas a través de PostgREST (RLS plus) SECURITY DEFINER RPCs que comprueba el rol de la persona que llama) y las operaciones sensibles a través de funciones de borde que mantienen el rol de servicio del lado del servidor. CRM escribe nunca vienen del cliente: activadores en supporters y forms_eventos llamada crm_ingest() dentro de la base de datos.

05Por dentro

Backend y datos
  • Tablas 67 en el esquema público (por los tipos generados), Migraciones 221 de Dic 2025 a Sep 2026, sobre las funciones 177 SQL y Funciones de borde deno 38 (8k líneas).
  • Roles en su propia mesa (user_roles, app_role enum) con has_role(), is_admin() y is_ativista() as SECURITY DEFINER, nunca en profiles.
  • Perfil único. crm_profiles tiene un UNIQUE teléfono normalizado; crm_events ha UNIQUE (profile_id, form_slug), un registro por persona por página; crm_field_history Almacena todos los cambios de campo. El origen de un perfil es siempre su registro más antiguo.
  • Una vía de ingestión. crm_ingest() es el único escritor en el CRM, llamado por los disparadores en tiempo real y por crm_backfill_core() / crm_backfill_crm_geral_batch() en lotes de 20,000, todo idempotente, para migrar la base heredada.
  • Lead Score. La puntuación es la suma de crm_score_events. Eventos automáticos llevan source='auto' y a source_ref, con un índice único parcial de (action_slug, source_ref); CSV importaciones dedupe en (profile_id, action_slug, occurred_on). El mismo registro nunca anota dos veces, mientras que un activista todavía puede obtener varias referencias en el mismo día. Las causas sensibles se dirigen a un flujo de atención y no puntúan.
  • Embudo y UTM. landing_pages, utm_links y page_events embudo de alimentación RPCs (get_funnel_overview, get_funnel_detail) y geográficos (get_crm_geo_overviewnormalizar los nombres de las ciudades con unaccent).
  • Integraciones Del lado del servidor. Registros son reenviados a puntos finales externos por un disparador utilizando pg_net (asíncrono, nunca bloquea el INSERT), con la clave API leída de Supabase Vault en lugar del código. pg_cron purga los registros de correo electrónico a diario.
  • Importación de puntuación a través de la import-score-csv función en tres fases (crm_start/apply/finish_score_import) con un registro por lotes.
Frontend
  • React 18, Vite 5 (SWC), TypeScript, Tailwind CSS 3 con tokens HSL semánticos, shadcn/ui en Radix.
  • Rutas 40 cargadas con lazy() y SuspenseTanStack Query v5 para el estado del servidor.
  • Formularios con react-hook-form + zodLos teléfonos siempre son capturados como (DD) 9XXXX-XXXX a través src/lib/phone.ts; parámetros de URL validados en urlParamValidation.ts.
  • supabaseFetchAll y la paginación de 1,000-row para moverse por PostgREST db-max-rows en grandes listas.
  • Recapitulación y react-simple-maps para gráficos y mapas; jsPDF + html2canvas para informes.
  • PWA vía vite-plugin-pwa: HTML se obtiene network-first en la navegación, por lo que se aplica una nueva versión sin una actualización dura, y los medios pesados se mantienen fuera del precaché.
Infraestructura y despliegue
  • Despliegue continuo de la parte delantera desde la rama principal, con un retroceso de SPA en public/_redirects.
  • Gestión de backend Supabase: Postgres, Auth, Almacenamiento, Edge Functions, pg_cron, pg_net y Vault.
  • Cuando se lanzó el sitio oficial de la campaña, el antiguo dominio comenzó a redirigirlo a través de un script en la parte superior de la página. <head>, mientras se mantiene /admin, /ativista, las rutas de activación, las páginas de destino y cualquier URL con ?ref= or ?utm_ intacto, por lo que los enlaces de referencia y la atribución de CRM siguieron funcionando.
  • No hay CI ni ningún conjunto de pruebas automatizadas en el repositorio.

06Seguridad

7 ataques considerados, 7 defensas en producción.

ataquedefensa
Atajo por la API

Saltarse la interfaz y hablar directo con la base o la API, con la clave pública en mano.

  • Llame al administrador RPCs o a los ayudantes de permisos con la clave pública

    EXECUTE revocado desde anon y público; funciones de administración comprobar is_admin() internamente

Cuentas e inicio de sesión

Fuerza bruta, creación indebida de cuentas, restablecimiento de contraseña y robo de cuenta.

  • Fuerza bruta o relleno de credenciales en el inicio de sesión de administrador y activista

    Turnstile en el inicio de sesión más un límite de fallas 5 por IP y 8 por correo electrónico cada 2 minutos, respondiendo 429 con Retry-After

Escalada de privilegios

Quien ya tiene algún acceso intentando ganar más: volverse admin, leer lo que no debe, conservar un acceso revocado.

  • Un activista autenticado tratando de leer toda la base de simpatizantes

    RLS: los activistas solo leen su propia fila y sus referencias; las tablas de CRM son solo para administradores

Origen y solicitudes falsificadas

CSRF, webhooks falsos, tokens reutilizados, enlaces firmados y redirección abierta.

  • Eventos de Forge email-provider

    Firma Svix verificada en el cuerpo crudo antes de cualquier procesamiento

  • Forjar un enlace de activación para tener una cuenta

    Enlace firmado con HMAC-SHA256 a través del uid y verificado del lado del servidor

Fuga y rastreo de datos

Enumerar quién está en la base, raspar datos personales, vincular preguntas a personas, extraer secretos.

  • Suscríbase a los canales en tiempo real para recibir datos de la tabla de administración

    RLS en realtime.messages restringido a administradores

Adulteración y rastro

Alterar conteos, borrar la base, editar el historial o negar lo que fue autorizado.

  • Limpie la base de apoyo en una sola operación

    Un disparador a nivel de sentencia rechaza los DELETE sobre las filas 5; un registro de auditoría mantiene una instantánea de cada fila eliminada

Autenticación

  • Admin y activista de inicio de sesión pasa por el login función, que requiere un server-verified Cloudflare Turnstile token y aplica un Límite de tarifa two-key: Fallos de 5 por IP y 8 por correo electrónico en una ventana de minutos 2, respondiendo 429 con Retry-After. Las direcciones IP se almacenan solo como hashes SHA-256.
  • Política de contraseñas: al menos caracteres 8, una letra mayúscula y un dígito.
  • Activación de la cuenta a través de un enlace firmado con HMAC-SHA256 (uid + sig, base64url), verificó del lado del servidor antes de que se pueda establecer una contraseña.
  • Un aviso de monitoreo discreto en las pantallas de inicio de sesión.

Autorización y RLS

  • RLS en todas las mesas públicas, con GRANTs en la misma migración.
  • Un activista lee supporters solo para su propia fila y sus referencias (referred_by_supporter_id = get_ativista_supporter_id(auth.uid())); solo los administradores actualizan o eliminan.
  • Tablas CRM: solo para administradores lee, escribe solo a través de SECURITY DEFINER funciones.
  • EXECUTE revocado de anon (y public) en el administrador RPCs y en los ayudantes RLS tales como is_admin, has_role y los generadores código de recomendación. Las funciones internas CRM no se pueden llamar a través de API.
  • En tiempo real bloqueado: RLS en realtime.messages limitado a los administradores, porque de lo contrario cualquier usuario de autenticado podría suscribirse a los canales de las tablas de administración, incluso mientras que la tabla RLS bloqueaba una suscripción directa. SELECT.
  • Las funciones de borde de administración validan el JWT y llaman is_admin() antes de actuar.

Formas y abuso

  • Anonimo INSERT on supporters fue revocado: la única ruta pública registro es la submit-form función, que comprueba Turnstile y escribe solo en la lista blanca columnas, inyección de columna de bloqueo a través de PostgREST.
  • Los puntos finales de búsqueda pública devuelven el mínimo, ningún nombre o rol, para limitar la enumeración.
  • Webhooks: Svix firma verificada en el cuerpo crudo antes de analizar (proveedor de correo electrónico); encabezados shared-secret en integraciones de automatización.

Protección de datos

  • supporters_audit_log mantiene una instantánea JSON de cada partidario eliminado, con quién lo eliminó, su rol y origen, legible solo por los administradores.
  • Mass-delete guardia: un disparador a nivel de sentencia rechaza cualquier DELETE on supporters tocar más de las filas 5 a menos que se establezca una omisión de sesión explícita.
  • Eliminación de cuenta Autoservicio desactivada pendiente de revisión después de un incidente.
  • Secretos de integración guardados fuera del código: variables de entorno de función de borde y Supabase Vault para llamadas realizadas desde la base de datos.

LGPD

  • Banner de consentimiento público y política de privacidad, hash de direcciones IP en el seguimiento de inicio de sesión, modo de privacidad para mostrar el panel sin exponer datos personales, y los activistas solo ven datos completos para sus propias referencias.

07Desafíos técnicos

Fusión de la base sin perder la historia

Registros vivía en varias tablas con teléfonos en diferentes formatos, y la función heredada digit-cleaning tenía un error: su translate También despojó al dígito 0, produciendo llaves incorrectas. La solución era una nueva capa encima de las tablas existentes en lugar de un reemplazo: crm_digits() con regexp_replace, crm_normalize_phone() (suelta el código del país, requiere al menos 10 dígitos), a UNIQUE teléfono normalizado y una única función de ingestión compartida por los disparadores y el relleno por lotes. La primera liberación revocada EXECUTE on crm_digits y rompió registros público en la producción (42501), porque un índice funcional sobre supporters evalúa la función con los privilegios del rol de inserción; la revisión concedida EXECUTE de nuevo en esa función pura y la regla fue documentada.

Puntuación idempotente de dos fuentes

Los eventos importado desde CSV y los eventos automáticos necesitan reglas duplicadas diferentes. Dos índices únicos parciales (por día para importaciones, por fuente para eventos automáticos) permiten que la base de datos decida, por lo que reprocesar registros o re-importing un archivo nunca infla una puntuación.

Un incidente mass-deletion

En abril 2026, los partidarios fueron eliminados en masa. El registro de auditoría había estado en su lugar durante cuatro días, por lo que una migración reinsertó las filas de la última instantánea de cada ID (jsonb_populate_record, ON CONFLICT DO NOTHING) y, en la misma migración, añadió el protector a nivel de sentencia usando una tabla de transición. Self-deletion fue desactivado, y tres días más tarde otra migración revocada anon EXECUTE en el administrador RPCs y denegó a usuarios sin rol de administrador cualquier lectura en la cola de aprobación.

Registros perdido en el navegador

El evento registros fue reenviado a un endpoint externo por un front-end fetch, expuestos al almacenamiento en caché PWA, bloqueadores y malas conexiones. La llamada se trasladó a pg_net desencadenador que es asíncrono, nunca falla el INSERT y lee su clave de Vault; la PWA cambió a network-first HTML para que las correcciones llegaran a los usuarios sin una actualización dura.

08Resultados

  • En producción desde diciembre 2025 hasta septiembre 2026, con confirmaciones 1,847 y migraciones 221.
  • Funciones de borde 38, tablas 67, sobre funciones 177 SQL, rutas 40 cargadas perezosamente.
  • La movilización CRM se envió como una serie de solicitudes de extracción 28 entre julio 2 y 6, 2026: perfil único, puntaje de plomo automático, embudo UTM, mapa geográfico, Turnstile y el bloqueo anonymous-INSERT.
1,847
compromisos
cómo lo medimos

git rev-list --cuenta la cabeza

221
Migraciones
cómo lo medimos

es supabase/migrations wc -l

38
funciones de borde
cómo lo medimos

es supabase/functions wc -l

67
cuadros
cómo lo medimos

Sección de tablas de src/integrations/supabase/types.ts

~177
Funciones SQL
cómo lo medimos

nombres distintos en CREAR [O REEMPLAZAR] FUNCIN a través de las migraciones

40
Rutas de con carga diferida
cómo lo medimos

grep -c 'perezoso(' src/App.tsx

~53k
Líneas TS/TSX
cómo lo medimos

wc -l en archivos .ts y .tsx rastreados (incluye funciones de borde y tipos generados)

~14k
Líneas SQL
cómo lo medimos

wc -l en supabase/migrations/*.sql

Dic 2025 - Sep 2026
marco de tiempo
cómo lo medimos

git log (primer código confirma 2025-12-15, último 2026-09-28)

09Línea de tiempo

  1. dic 2025

    Kickoff: landing page registro y un embudo de reclutamiento gamificado

  2. ene 2026

    El mes más ocupado (635 se compromete): área activista, CRM y marketing por correo electrónico

  3. abr 2026

    Registro de auditoría, recuperación de una eliminación masiva, protección DELETE y bloqueo en tiempo real y RPC

  4. jul 2026

    Movilización CRM: perfil único, Lead Score automático, embudo UTM y mapa (28 PRs en 5 días)

  5. jul 2026

    Turnstile en registro e inicio de sesión, y INSERT anónimo revocado

  6. ago 2026

    Integración con el sitio oficial y una redirección que mantiene las referencias y UTMs

  7. sep 2026

    Páginas de página de destino del evento final y fin del desarrollo

10Stack

Frontend
  • React 18
  • Vite 5 (SWC)
  • TypeScript 5
  • Tailwind CSS 3
  • shadcn/ui
  • Radix UI
  • TanStack Query 5
  • React Router 6
  • react-hook-form
  • zod
  • Recharts
  • react-simple-maps
  • jsPDF
Backend
  • Supabase Edge Functions (Deno)
  • PostgREST
  • PL/pgSQL SECURITY DEFINER
  • Supabase Auth
  • Resend
  • N8N
Datos
  • PostgreSQL
  • Row Level Security
  • pg_cron
  • pg_net
  • Supabase Vault
  • Supabase Storage
  • unaccent
Infra
  • Deploy contínuo via GitHub
  • PWA (vite-plugin-pwa)
  • GA4 Data API
Seguridad
  • Cloudflare Turnstile
  • Rate limit por IP e por e-mail
  • Hash de IP (SHA-256)
  • Links de ativação HMAC-SHA256
  • Webhooks Svix
  • Audit log + trava de DELETE em massa
  • RLS em realtime.messages

11Ficha técnica

node@pimenta-no-senado: ~/cases/pimenta-no-senado
node@pimenta-no-senado ─────────────
type
movilización CRM
stack
React 18 Vite TS
db
Postgres 67 tablas RLS
auth
Supabase Auth Turnstile límite de velocidad
edge
Funciones de borde 38 (Deno)
deploy
despliegue continuo + PWA
modules
registros activistas CRM puntuación de plomo
status
Completado
$ ls supabase/migrations | wc -l && ls supabase/functions | wc -l
221
38
$ psql -c "select crm_normalize_phone('+55 (11) 90000-0000')"
crm_normalize_phone
---------------------
11900000000
(1 row)
$ curl -s -X POST $FN/submit-form -d '{"data":{"nome_completo":"Teste","whatsapp":"11900000000"}}'
{"success":false,"error":"CAPTCHA","message":"Falha na verificação de segurança. Recarregue a página e tente novamente."}
$ grep -ri 'enable row level security' supabase/migrations | wc -l
72
$ psql -c "delete from supporters where created_at < now() - interval '1 day'"
ERROR: Mass delete em public.supporters bloqueado: tentativa de apagar 6 linhas em uma unica statement (limite: 5).
$ npm run build
vite v5.4.19 building for production...
✓ built

© 2026 NODE. Todos los derechos reservados.