recipient-lists

O submódulo Recipient Lists modela `campaign_recipient_list`, o contêiner de público que uma campanha aponta via `recipient_list_id`. Cada lista carrega um slug único e validado (letras minúsculas, números, hifens, no mínimo 2 caracteres — gerado automaticamente a partir do nome se não fornecido), uma classificação de `source` ("manual" | "import" | "crm" | "mixed") que reflete como seus destinatários foram populados e contadores consolidados (`total_recipients`, `total_active`, `total_unsubscribed`, `total_suppressed`, `total_invalid`) que o CampaignRecipientListService recalcula após cada mutação, em vez de computar na leitura. Todas as rotas são montadas em duplicidade tanto sob `/campaign/lists/*` quanto `/campaign/recipient-lists/*` — o controller registra cada handler duas vezes com o suporte a múltiplos decorators do NestJS — de modo que ambas as convenções de nomenclatura resolvem de forma idêntica; esta documentação usa `/campaign/recipient-lists/*` como a forma canônica.

Destinatários podem ser adicionados a uma lista de três maneiras. JSON inline (`POST .../recipients` com um array de objetos `{ email, name?, ... }` ou um atalho `{ email }` único) faz upsert por e-mail dentro da lista. A sincronização com o CRM (`person_ids` no mesmo endpoint) resolve o contato primário do tipo EMAIL de cada Person do CRM, pulando pessoas sem e-mail válido e reportando-as de volta em um array `skipped`, e então muda o `source` da lista para "mixed" (ou "crm" se todos os destinatários vieram do CRM) assim que pelo menos uma pessoa é adicionada. A importação por CSV é um fluxo em duas etapas: `POST .../recipients/import/preview` faz o parsing do arquivo enviado (parser de CSV artesanal e customizado, suportando tanto delimitadores de vírgula quanto de ponto e vírgula e campos entre aspas, limitado a 10 MB / reforçado novamente em 5000 linhas de dados) e retorna as colunas detectadas mais uma amostra de 20 linhas sem persistir nada; `POST .../recipients/import` recebe o mesmo arquivo mais um `mapping` JSON das colunas do CSV para os campos de destinatário e realiza o upsert-por-e-mail de fato, opcionalmente vinculando cada linha importada a uma empresa existente do CRM via `company_id`.

O cadastro público (`POST /campaign/lists/:slug/signup`, não autenticado) permite que uma lista aceite inscrições self-service. Ele só funciona quando `allow_public_signup` é true na lista; quando `enable_captcha` também é true, o Integration Profile de CAPTCHA configurado (reCAPTCHA, Cloudflare Turnstile ou Altcha) é invocado para validar o `captcha_token` enviado antes de o e-mail sofrer upsert. Este é o ponto de entrada típico para formulários de inscrição em newsletter incorporáveis.

O submódulo também hospeda o cursor de tempo real da campanha (`GET /campaign/realtime/cursor`, `GET /campaign/realtime/stream`): cada mutação de lista chama `CampaignRealtimeService.publish()`, incrementando um contador de sequência em memória que as UIs de admin consultam por polling ou assinam via Server-Sent Events para saber quando refazer o fetch dos dados da lista, sem que o servidor rastreie o estado por cliente.