# Documentação de Módulos ## Visão Geral O sistema é composto por 7 módulos funcionais em `src/modules/`: 1. **`auth`**: Autenticação de credenciais e cadastro de usuários no sistema. 2. **`campaigns`**: Criação, edição, agendamento, disparo em lotes, métricas e relatórios de campanhas. 3. **`contacts`**: Gestão completa de contatos, listas de transmissão, tags, importação/exportação CSV e histórico de envios. 4. **`domains`**: Gerenciamento de domínios customizados e verificação de registros DNS (DKIM/SPF) no AWS SES. 5. **`senders`**: Cadastro e criptografia de remetentes de e-mail (SMTP e SES). 6. **`ses-webhooks`**: Recepção de eventos do AWS SES/SNS e pixel de rastreamento de aberturas. 7. **`suppression`**: Consulta e remoção de e-mails na lista de supressão por bounce ou reclamação de SPAM. --- ## 1. `auth` ### Responsabilidade Gerencia a autenticação via credentials do NextAuth v5 e a criação de novas contas de usuário. ### Server Actions - `registerAction(data)`: Registra um novo usuário no sistema validando nome, e-mail e senha. ### Use-Cases - `AuthenticateUserUseCase`: Autentica o e-mail e verifica a hash bcrypt da senha. - `RegisterUserUseCase`: Valida duplicação de e-mail, gera a hash bcrypt da senha e cria o registro do usuário. ### Repositórios - `UsersRepository` (Interface) - `PrismaUsersRepository`: Busca por e-mail e ID via Prisma. - `InMemoryUsersRepository`: Repositório em memória para testes. --- ## 2. `campaigns` ### Responsabilidade Criação, envio, relatórios e métricas de campanhas de e-mail marketing. ### Server Actions - `createCampaignAction(data)`: Cria um rascunho de campanha. - `updateCampaignAction(id, data)`: Atualiza título, assunto e lista de transmissão de um rascunho. - `dispatchCampaignAction(id)`: Inicia o disparo síncrono/loteado de uma campanha. - `sendTestAction(campaignId, testEmail)`: Envia um e-mail de teste individual. - `retryFailedAction(campaignId)`: Re-tenta o disparo de mensagens que falharam em uma campanha. - `resendCampaignToContactAction(campaignId, contactId)`: Re-envia a campanha para um contato específico. - `getCampaignReportAction(id)`: Retorna métricas detalhadas da campanha (envios, aberturas, bounces). - `getDashboardAnalyticsAction()`: Retorna métricas consolidadas do dashboard principal. ### Use-Cases - `CreateCampaignUseCase`: Cria uma nova campanha vinculando remetente e lista. - `UpdateCampaignUseCase`: Altera as propriedades de uma campanha em rascunho. - `DispatchCampaignUseCase`: Carrega a lista de contatos ativos (não suprimidos), gera os logs de campanha e dispara as mensagens em lotes concorrentes via `MailProvider`. - `SendTestCampaignUseCase`: Envia uma mensagem de teste usando o remetente da campanha. - `RetryFailedCampaignUseCase`: Identifica `CampaignLog` com status `FAILED` e re-tenta o envio. - `ResendCampaignToContactUseCase`: Re-dispara a campanha para um único contato. - `GetCampaignByIdUseCase`: Busca os detalhes da campanha e seus logs. - `GetCampaignsByUserUseCase`: Lista todas as campanhas do usuário. - `GetCampaignsSummaryByUserUseCase`: Retorna resumo estatístico das campanhas do usuário. - `GetDashboardAnalyticsUseCase`: Calcula taxas globais de entrega, abertura, cliques e bounces. ### Repositórios - `CampaignsRepository` / `PrismaCampaignsRepository` / `InMemoryCampaignsRepository` - `CampaignLogsRepository` / `PrismaCampaignLogsRepository` / `InMemoryCampaignLogsRepository` ### Providers (Mail Transports & Rate Limiter) - `MailProviderFactory`: Instancia `SesMailProvider` ou `NodemailerMailProvider` conforme o remetente. - `NodemailerMailProvider`: Envio de e-mail via SMTP (suporta Mailpit em desenvolvimento). - `SesMailProvider`: Envio via SDK AWS SES v2 (`@aws-sdk/client-sesv2`). - `InMemoryMailProvider`: Provedor fake para testes unitários. - `RateLimiter`: Controla a taxa máxima de requisições por segundo. - `runInBatches`: Utilitário para execução assíncrona concorrente em lotes. ### Entities - `build-email-content.ts`: Injeta o pixel de rastreamento de abertura e o cabeçalho/link de descadastro (`List-Unsubscribe`). - `sanitize-html.ts`: Sanitiza o corpo HTML da campanha via `sanitize-html` para evitar XSS. - `html-to-plain-text.ts`: Converte HTML em texto puro via `cheerio` para a versão alternativa do e-mail. --- ## 3. `contacts` ### Responsabilidade Gestão completa da base de contatos, segmentação em listas, tags de organização, importação em massa via CSV, exportação assíncrona e histórico de engajamento por e-mail. ### Funcionalidades Chave - **CRUD de Contatos**: Cadastro individual, edição e exclusão. - **Listas de Contatos**: Criação de listas/segmentos de transmissão por canal (E-mail/SMS). - **Tags**: Gerenciamento de tags e fusão (*merge*) de duas tags em uma única. - **Importação CSV em Lotes**: Parsing do CSV (`papaparse`), interface de mapeamento de colunas, estratégias de duplicação (`IGNORE`, `UPDATE`, `CREATE_ANYWAY`) e processamento assíncrono em lotes com relatório de erros. - **Exportação CSV**: Geração de arquivo CSV dos contatos com filtros aplicados. - **Histórico por Contato**: Timeline de e-mails enviados, entregues, abertos e bounces. ### Server Actions (26 Actions) - `createContactAction`, `updateContactAction`, `deleteContactAction`, `getContactByIdAction`, `getContactsPaginatedAction` - `bulkUpdateContactsAction`, `assignContactsToListsAction` - `createContactListAction`, `deleteContactListAction`, `getAllContactListsAction`, `getContactListsPaginatedAction` - `createTagAction`, `updateTagAction`, `deleteTagAction`, `getTagsPaginatedAction`, `mergeTagsAction` - `parseContactImportAction`, `confirmImportMappingAction`, `processImportBatchAction`, `getImportJobAction`, `exportImportErrorsAction` - `exportContactsAction`, `getExportHistoryAction`, `downloadContactExportAction` - `getContactEmailHistoryAction`, `exportContactEmailHistoryAction` ### Repositórios - `ContactsRepository` / `PrismaContactsRepository` / `InMemoryContactsRepository` - `ContactListsRepository` / `PrismaContactListsRepository` / `InMemoryContactListsRepository` - `TagsRepository` / `PrismaTagsRepository` / `InMemoryTagsRepository` - `ContactImportJobsRepository`, `ContactImportRowsRepository`, `ContactExportJobsRepository` ### Entities & Utils - `map-import-row.ts`: Transforma linhas brutas do CSV em objetos de contato. - `derive-email-engagement.ts`: Calcula o nível de engajamento do contato com base em aberturas e entregas. - `build-contacts-export-csv.ts`, `build-import-errors-csv.ts`, `build-email-history-csv.ts`: Geradores de strings CSV. --- ## 4. `domains` ### Responsabilidade Gerenciamento de domínios de envio para uso com o AWS SES, incluindo geração de registros DNS para validação de identidade e DKIM. ### Server Actions - `createDomainAction(data)`: Registra um novo domínio e inicia o provisionamento no AWS SES. - `verifyDomainAction(domainId)`: Consulta o status atual de verificação dos registros DNS na AWS. - `deleteDomainAction(id)`: Apaga o domínio do sistema. - `getDomainsByUserAction()`: Lista os domínios do usuário logado. ### Use-Cases - `CreateDomainUseCase`: Chama o `SesIdentityProvider` para criar a identidade no SES e salvar os registros DKIM gerados. - `VerifyDomainUseCase`: Re-consulta a AWS para verificar se os registros CNAME/DKIM foram propagados. - `PollPendingDomainsUseCase`: Varre todos os domínios com status `PENDING` e atualiza seu estado no banco de dados. - `BootstrapSesInfraUseCase`: Provisiona o Configuration Set padrão do SES, tópico SNS e destino de eventos. ### Providers & Entities - `SesIdentityProviderImpl`: Integração direta com AWS SES API v2 para gerenciamento de identidades. - `build-dns-records.ts`: Formata os registros CNAME e TXT que o usuário deve adicionar à sua zona DNS. --- ## 5. `senders` ### Responsabilidade Gerenciamento dos remetentes de e-mail (endereços "De:") e suas credenciais de autenticação SMTP ou associação com domínios SES. ### Segurança As senhas de servidores SMTP são **criptografadas com AES-256-GCM** antes de serem persistidas no banco (`smtpPass`) através de utilitários em `src/shared/infra/crypto/crypto.ts`. A chave de criptografia é definida via `ENCRYPTION_KEY`. ### Server Actions - `createSenderAction(data)`: Cadastra um remetente SMTP ou SES. - `updateSenderAction(id, data)`: Atualiza as configurações e senha do remetente. - `deleteSenderAction(id)`: Remove o remetente (bloqueado se houver campanhas associadas). - `getSendersByUserAction()`: Lista os remetentes do usuário logado. --- ## 6. `ses-webhooks` ### Responsabilidade Processamento de notificações enviadas pela AWS (via SNS Webhooks) sobre eventos de e-mail (entregas, bounces, reclamações de SPAM) e captura de aberturas via pixel estático. ### Handlers HTTP - `POST /api/webhooks/ses`: Webhook que recebe notificações SNS. - Confirma assinaturas de tópico (`SubscriptionConfirmation`). - Valida assinaturas de segurança RSA do envelope SNS via `verifySnsMessage`. - Executa `HandleSesNotificationUseCase` para atualizar logs de campanha, registrar `EmailEvent` e suprimir e-mails no caso de Hard Bounces ou Complaints. - `GET /api/track/open/[token]`: Pixel de rastreamento de abertura (GIF transparente 1x1 estático). - Executa `RecordEmailOpenUseCase` e sempre retorna HTTP 200 com imagem GIF estática. --- ## 7. `suppression` ### Responsabilidade Gerenciamento da lista de e-mails suprimidos (bloqueados para envio para proteger a reputação do remetente). ### Server Actions - `getSuppressedEmailsAction()`: Lista todos os e-mails na lista de supressão. - `removeSuppressedEmailAction(id)`: Remove um e-mail da lista de supressão (permitindo novos envios). ### Use-Cases & Repositórios - `RemoveSuppressedEmailUseCase`: Remove a entrada da tabela `suppressed_emails`. - `SuppressedEmailsRepository` / `PrismaSuppressedEmailsRepository` / `InMemorySuppressedEmailsRepository`.