Devocional Diário via WhatsApp

Palavra Diária — Especificação Técnica Completa #

Devocional cristão diário em texto e áudio, entregue no WhatsApp. Modelo freemium, cobrança recorrente pela Asaas, painel próprio do assinante e painel administrativo editorial. Mercado brasileiro, português do Brasil.

Versão 1.0 — Final

Visão Geral do Documento #

Este documento especifica, de ponta a ponta, um sistema que entrega um devocional cristão todos os dias às 06:00 (America/Sao_Paulo) no WhatsApp do assinante, em texto e em áudio narrado. O plano gratuito recebe o devocional em texto uma vez por semana, aos domingos. O plano pago recebe texto e áudio todos os dias.

Ele foi escrito para ser executado por um agente de IA trabalhando sozinho, sem poder fazer perguntas. Toda decisão de produto, de arquitetura, de dados, de segurança e de operação já está tomada e registrada aqui. Onde havia mais de um caminho razoável, a escolha foi feita e justificada; onde havia restrição externa — as regras de mensagem do WhatsApp, o modelo de cobrança da Asaas, a LGPD — a restrição é descrita antes da solução que a atende.

Três decisões estruturam o resto do documento e vale conhecê-las antes de ler:

1. A entrega do áudio contorna uma restrição real da plataforma. A API do WhatsApp não permite enviar áudio como primeira mensagem do dia, e não permite texto com parágrafos dentro de um template. O sistema resolve isso com o desenho "Template + Janela": um convite curto por template às 06:00 abre a janela de atendimento de 24 horas, e o devocional completo e o áudio seguem como mensagens livres dentro dessa janela. A Seção 17 descreve o desenho e o que aconteceria em cada alternativa descartada.
2. Falha de pagamento encerra o acesso pago na hora, sem carência. Essa é uma regra de negócio explícita do produto, não um efeito colateral de implementação. Ela é diferente do cancelamento voluntário, em que o assinante mantém o acesso até o fim do período que já pagou. A Seção 13 separa os dois casos com linhas do tempo.
3. Cada assunto tem uma seção dona. O schema do banco é da Seção 6; o contrato de API é da Seção 7; a matriz de planos é da Seção 13; as variáveis de ambiente são da Seção 26. As demais seções referenciam a dona em vez de repetir a definição, para que nada divirja.

Como ler. Um executor deve começar pela Seção 30, que explica a ordem de leitura e as regras invioláveis, e depois seguir o plano de milestones da Seção 28. Um leitor de negócio encontra o essencial nas Seções 1, 2 e 13. A Seção 1 lista as decisões que podem ser trocadas antes da execução, cada uma já com um padrão que vale caso ninguém responda.

Índice #

1. Antes de Começar — Decisões Configuráveis
2. Visão Geral do Produto e Objetivos
3. Personas, Papéis e Matriz de Permissões
4. Arquitetura e Stack Tecnológica
5. Convenções de Código e Padrões de Projeto
6. Modelo de Dados e Schema do Banco
7. Design de API — Contratos, Erros e Padrões
8. Autenticação, Sessões e Autorização
9. Landing Page e Página de Vendas — Especificação Funcional
10. Copy Aprovado — Página de Vendas e Mensagens ao Assinante
11. Cadastro, Opt-in e Onboarding do Assinante
12. Integração de Pagamentos — Asaas
13. Assinaturas: Ciclo de Vida, Inadimplência e Entitlements
14. Painel do Assinante
15. Painel Administrativo e Calendário Editorial
16. Geração de Áudio (TTS) e Pipeline de Mídia
17. Integração WhatsApp Business Cloud API
18. Motor de Envio Diário
19. Catálogo de Mensagens e Fluxos Conversacionais
20. Cancelamento, Opt-out e Retenção
21. Dashboard de Métricas e Analytics
22. Segurança, Privacidade e LGPD
23. Observabilidade, Logs, Métricas e Alertas
24. Estratégia de Testes e QA
25. Infraestrutura, Deploy e CI/CD
26. Registro de Configuração e Variáveis de Ambiente
27. Tratamento de Erros, Resiliência e Runbooks Operacionais
28. Plano de Execução e Milestones
29. Critérios de Aceitação
30. Instruções para o Agente Executor
31. Glossário e Referências Externas

1. Antes de Começar — Decisões Configuráveis #

Esta seção existe para uma finalidade única: permitir que o dono do produto ajuste o serviço antes da primeira linha de código, sem abrir nenhuma outra seção do documento. Cada item abaixo é uma pergunta fechada, com um padrão já decidido. Nada aqui bloqueia a execução.

1.1 Como usar esta seção #

1. Leia as perguntas de 1.3 a 1.30. Responda apenas as que você quer mudar.
2. O que não for respondido entra em produção com o padrão indicado.
3. O executor registra cada resposta no local indicado em "Onde impacta". Há três locais possíveis, e a escolha do local não é livre:
   • Variável de ambiente — valores de infraestrutura, credenciais e chaves de operação. Catálogo normativo na Seção 26.
   • Tabela settings — valores de negócio que o administrador pode mudar em produção sem novo deploy (preço exibido, dia do envio gratuito, limites de reenvio, texto de consentimento). Estrutura da tabela na Seção 6.
   • Código versionado — identidade visual, textos de interface, tokens de tema.
4. Nenhuma resposta desta seção altera o schema do banco, os contratos de API ou a máquina de estados da assinatura. Se uma resposta parecer exigir isso, ela está fora do escopo do MVP e deve ser tratada como pedido de mudança, não como configuração.

1.2 Regra de não bloqueio #

Ausência de resposta nunca interrompe a execução. O executor aplica o padrão listado, anota a decisão no README.md do repositório sob o título "Decisões configuráveis aplicadas" e segue para a próxima tarefa. Perguntar ao dono do produto e esperar resposta é comportamento proibido nesta fase.

1.3 Q01 — Nome comercial do serviço #

• Pergunta: qual é o nome comercial exibido ao público?
• Por que importa: aparece na landing, nos e-mails, no nome de exibição do WhatsApp, nos termos de uso e no cabeçalho dos painéis. Trocar depois exige revisar textos aprovados e reenviar templates para aprovação da Meta.
• Onde impacta: Seção 9 (landing), Seção 10 (copy aprovado), Seção 17 (nome de exibição do remetente). Código: apps/web/src/i18n/pt-BR.ts, chave brand.name.
• Padrão: Palavra Diária. O identificador técnico do monorepo e dos artefatos permanece palavra-diaria mesmo que o nome comercial mude, para evitar renomeação de imagens Docker, buckets e filas.

1.4 Q02 — Domínio e subdomínios #

• Pergunta: qual domínio de produção e qual a divisão de subdomínios?
• Por que importa: define emissão de certificado TLS, cookies de sessão, URLs de webhook registradas na Asaas e na Meta, e o canonical de SEO. Mudar depois exige reconfigurar os dois provedores externos e invalidar sessões.
• Onde impacta: Seção 9 (SEO e rotas públicas), Seção 12 (URL do webhook da Asaas), Seção 17 (URL do webhook da Meta), Seção 25 (Caddy e TLS), Seção 26 (APP_URL).
• Padrão: palavradiaria.com.br para o site público, app.palavradiaria.com.br para os painéis do assinante e administrativo, api.palavradiaria.com.br para webhooks e API pública. Cookie de sessão com prefixo __Host-, portanto sem Domain e restrito ao host que o emitiu (ver Seção 8).

1.5 Q03 — Paleta de cores #

• Pergunta: quais são as cores da marca?
• Por que importa: todo o tema é gerado a partir de tokens; contraste insuficiente reprova os critérios de acessibilidade WCAG 2.2 AA exigidos na Seção 9.
• Onde impacta: Seção 9 e Seção 14. Código: apps/web/src/styles/theme.css (tokens CSS consumidos pelo Tailwind) e apps/web/src/components/ui/*.
• Padrão: primária #1F4E5F (azul-petróleo), secundária #C8873B (âmbar), fundo claro #FAF8F4, texto #1A1A1A, sucesso #2E7D5B, erro #B3261E, aviso #8A6100. Todos os pares texto/fundo validados com contraste mínimo de 4,5:1 para texto normal e 3:1 para texto grande e elementos de interface. Tema escuro derivado por inversão de luminância, não por cores novas.

1.6 Q04 — Tipografia #

• Pergunta: quais famílias tipográficas, e elas são auto-hospedadas?
• Por que importa: fonte externa adiciona uma requisição de terceiro na rota crítica da landing e conflita com a meta de desempenho da página de vendas (Seção 9). Fonte de leitura ruim prejudica o texto do devocional no painel.
• Onde impacta: Seção 9 (desempenho e SEO). Código: apps/web/app/layout.tsx e apps/web/src/styles/theme.css.
• Padrão: títulos em Fraunces (serifada, peso 600), corpo em Inter (peso 400/600), ambas auto-hospedadas em apps/web/public/fonts/ com font-display: swap e subset latin-ext. Tamanho base de 17 px no corpo do devocional, altura de linha 1,7.

1.7 Q05 — Logo, favicon e imagem de compartilhamento #

• Pergunta: existe logo pronto? Em quais formatos?
• Por que importa: ausência de logo trava a landing, o cabeçalho dos painéis, o og:image e o perfil comercial do WhatsApp.
• Onde impacta: Seção 9 (Open Graph), Seção 17 (perfil comercial). Código: apps/web/public/brand/logo.svg, logo-mark.svg, favicon.ico, og-default.png.
• Padrão: marca tipográfica gerada com a tipografia de Q04 sobre a cor primária de Q03, mais um símbolo de sol nascente em traço único. Entregues em SVG, PNG 512×512 (perfil do WhatsApp exige imagem quadrada) e PNG 1200×630 para og:image.

1.8 Q06 — Preço do plano mensal #

• Pergunta: qual o valor mensal em reais?
• Por que importa: define o value enviado à Asaas na criação da assinatura, o MRR e a viabilidade do custo por assinante. Alterar o preço não altera assinaturas já ativas.
• Onde impacta: Seção 12 (criação da assinatura na Asaas), Seção 13 (planos vigentes), Seção 21 (MRR). Dados: registro plan_monthly na tabela plans (Seção 6), semeado em packages/db/prisma/seed.ts.
• Padrão: R$ 19,90/mês, cobrança recorrente, sem período de teste gratuito.

1.9 Q07 — Preço do plano anual #

• Pergunta: qual o valor anual e qual o desconto implícito?
• Por que importa: o plano anual reduz o efeito de cartão negado e de churn involuntário, que é alto no Brasil, mas antecipa receita e aumenta o custo de reembolso.
• Onde impacta: Seção 12, Seção 13, Seção 21. Dados: registro plan_annual em plans.
• Padrão: R$ 199,00/ano, equivalente a R$ 16,58/mês, desconto de 16,7% sobre doze mensalidades. O número 16,7% é interno: o rótulo exibido ao público é sempre arredondado para baixo, portanto "economize 16%", para nunca prometer mais do que se entrega (regra de arredondamento na Seção 9.5). A página de planos usa "economize 16%" e "economize 2 meses" como chamada secundária.

1.10 Q08 — Formas de pagamento aceitas #

• Pergunta: aceitar cartão de crédito, PIX, ambos?
• Por que importa: cartão permite recorrência automática; PIX exige gerar uma cobrança nova a cada ciclo e depende de ação do assinante, o que muda o desenho de lembretes.
• Onde impacta: Seção 12 (fluxos de checkout), Seção 13 (renovação e inadimplência), Seção 19 (mensagens de lembrete).
• Padrão: CREDIT_CARD e PIX. Boleto fica fora do MVP por causa do prazo de compensação, que é incompatível com a regra de revogação imediata da Seção 13.

1.11 Q09 — Dia da semana do envio gratuito #

• Pergunta: em que dia o assinante do plano gratuito recebe seu devocional semanal?
• Por que importa: define o pico de volume semanal, o custo de mensagens do dia e a janela em que a conversão para o plano pago é mais provável.
• Onde impacta: Seção 13 (entitlements), Seção 18 (cálculo do lote diário). Dados: chave send.free_tier_weekday na tabela settings (catálogo na Seção 26.8.1). Não existe variável de ambiente equivalente: o dia do envio gratuito é decisão de negócio e vive exclusivamente em settings.
• Padrão: domingo (0, no padrão em que domingo é 0 e sábado é 6). Exemplo: em um cenário de 7.000 assinantes gratuitos e 3.000 pagos, o domingo dispara 10.000 envios e os demais dias, 3.000.

1.12 Q10 — Horário do envio diário #

• Pergunta: a que horas o devocional chega?
• Por que importa: é a promessa central do produto. Também define o horário do planejamento do lote e a janela de manutenção, que não pode colidir com o envio.
• Onde impacta: Seção 18 (motor de envio), Seção 23 (alertas de atraso). Dados: chaves send.daily_hour_local e send.plan_offset_minutes em settings (Seção 26.8.1).
• Padrão: 06:00 no fuso America/Sao_Paulo, com o job de planejamento do lote às 05:40 local. O fuso é sempre o nomeado America/Sao_Paulo; deslocamento numérico fixo é proibido (Seção 30.3, regra 13). O sistema não oferece horário personalizado por assinante — isso é explicitamente fora de escopo (ver Seção 2.7).

1.13 Q11 — Versão bíblica utilizada #

• Pergunta: qual tradução da Bíblia será citada nos devocionais?
• Por que importa: traduções modernas amplamente conhecidas são obras licenciadas. Publicar versículos delas em um produto pago, sem contrato, é risco jurídico real.
• Onde impacta: Seção 15 (editor de conteúdo, campo bible_version), Seção 22 (risco jurídico e direitos autorais). Dados: chave content.bible_version_default em settings (Seção 26.8.1).
• Padrão: ALMEIDA_1911 — a Almeida Revista e Corrigida na edição de 1911, em domínio público — com BIBLIA_LIVRE (Almeida Livre / Bíblia Livre) como alternativa aceita. A sigla ARC é proibida como código e como atribuição: no mercado brasileiro ela identifica a Almeida Revista e Corrigida em edição revisada por editora ativa, que é obra protegida, e não a edição de 1911. A atribuição impressa em toda entrega é João 3:16 (Almeida 1911) ou João 3:16 (Bíblia Livre), nunca uma sigla ambígua. O campo bible_version é obrigatório em todo devocional, aceita apenas os valores da lista fechada e o painel administrativo bloqueia a publicação se estiver vazio. Adotar uma tradução licenciada exige contrato assinado antes da publicação, e essa decisão não é configuração — é mudança de escopo.

1.14 Q12 — Provedor de TTS e voz #

• Pergunta: qual provedor de síntese de voz e qual voz específica?
• Por que importa: a voz é a identidade sonora do produto. Trocar depois de o acervo estar publicado gera inconsistência entre devocionais antigos e novos.
• Onde impacta: Seção 16 (pipeline de áudio). Configuração: TTS_PROVIDER, TTS_VOICE_ID, TTS_MODEL_ID (Seção 26).
• Padrão: ElevenLabs como provedor primário, modelo multilíngue corrente, voz feminina brasileira de timbre grave e ritmo pausado, stability=0.45, similarity_boost=0.75, saída mp3_44100_128. Google Cloud TTS como fallback automático após três falhas consecutivas do primário. O provedor efetivamente usado é gravado em cada ativo de áudio, para auditoria de custo e de timbre.

1.15 Q13 — Número e nome de exibição do WhatsApp #

• Pergunta: qual número de telefone e qual nome de exibição comercial?
• Por que importa: o nome de exibição passa por aprovação da Meta e não pode ser trocado livremente. O número é a identidade do remetente; perder acesso a ele é perder o canal.
• Onde impacta: Seção 17 (operação do canal), Seção 27 (runbook de bloqueio de número). Configuração: WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_BUSINESS_ACCOUNT_ID.
• Padrão: um número novo, dedicado e exclusivo do serviço, nunca um número já usado em aplicativo pessoal ou WhatsApp Business comum. Nome de exibição igual ao nome comercial de Q01. O número não recebe ligações e a mensagem de ausência informa o canal de suporte.

1.16 Q14 — Política de reenvio manual pelo painel #

• Pergunta: quantas vezes por dia o assinante pode pedir o reenvio do devocional do dia?
• Por que importa: cada reenvio é uma mensagem paga se estiver fora da janela de 24 horas. Limite alto abre espaço para abuso e para custo imprevisível.
• Onde impacta: Seção 13 (entitlements) e Seção 14 (painel do assinante). Dados: chaves resend.free_daily_limit e resend.paid_daily_limit em settings (Seção 26.8.1).
• Padrão: 1 reenvio por dia no plano gratuito e 3 por dia no plano pago, contados por dia de calendário em America/Sao_Paulo e reiniciados à meia-noite local. Exemplo: um assinante pago que pediu reenvio às 07:10, 12:30 e 19:45 recebe RESEND_LIMIT_REACHED na quarta tentativa do mesmo dia e volta a ter três créditos às 00:00 do dia seguinte.

1.17 Q15 — Limite do acervo no plano gratuito #

• Pergunta: quantos dias de histórico o assinante gratuito vê no painel web?
• Por que importa: o acervo é um dos dois principais motivos de conversão, junto com o áudio. Um limite generoso demais remove o incentivo de assinar.
• Onde impacta: Seção 13 (entitlements) e Seção 14 (listagem do acervo). Dados: chave archive.free_days em settings (Seção 26.8.1).
• Padrão: últimos 7 dias para o plano gratuito; acervo completo desde a primeira assinatura paga do assinante para o plano pago (regra detalhada na Seção 13.6.1: quem foi pago, deixou de ser e voltou, vê tudo desde a primeira vez). O limite é imposto no servidor, não apenas na interface. Exemplo: em 25/08, o gratuito enxerga devocionais de 19/08 a 25/08; itens anteriores aparecem bloqueados, com chamada para assinar, e não desaparecem da lista — o bloqueio visível converte melhor do que a ausência.

1.18 Q16 — Texto do consentimento LGPD #

• Pergunta: qual o texto exato do aceite exibido no cadastro?
• Por que importa: o consentimento é a base legal do envio de mensagens. Ele é gravado em formato imutável, com versão, e precisa ser exibível anos depois exatamente como foi aceito.
• Onde impacta: Seção 11 (formulário de cadastro), Seção 22 (LGPD e prova de consentimento). Dados: chave privacy.policy_version em settings (Seção 26.8.1); o texto de cada versão fica em apps/web/src/legal/consent/, versionado no repositório.
• Padrão: versão v1, com o texto: "Autorizo o envio de mensagens no meu WhatsApp com o devocional diário e avisos sobre a minha assinatura. Posso cancelar a qualquer momento respondendo SAIR. Li e aceito os Termos de Uso e a Política de Privacidade." O aceite é registrado com data e hora, endereço IP, agente de usuário, canal e versão do texto. Alterar o texto exige criar v2 — nunca editar v1 no lugar.

1.19 Q17 — Encarregado de dados (DPO) e canal do titular #

• Pergunta: quem é o encarregado e qual e-mail público?
• Por que importa: a LGPD exige indicação de encarregado com canal de contato divulgado. A ausência é infração autônoma, independente de vazamento.
• Onde impacta: Seção 22 (privacidade e direitos do titular), Seção 9 (rodapé e página de privacidade). Configuração: chave privacy.dpo_email em settings (Seção 26.8.1).
• Padrão: privacidade@palavradiaria.com.br, com resposta em até 15 dias corridos. Esta seção é a dona do valor padrão (Seção 30.2); o seed grava exatamente este endereço em privacy.dpo_email. O nome do encarregado é publicado na página de privacidade. Enquanto não houver indicação formal de terceiro, o encarregado é o sócio responsável pela operação.

1.20 Q18 — Razão social, CNPJ e endereço nos termos #

• Pergunta: qual entidade jurídica figura nos termos, na política de privacidade e no recibo de pagamento?
• Por que importa: contrato de adesão sem parte identificada é inexequível, e a Asaas vincula a conta de recebimento a um CNPJ ou CPF específico.
• Onde impacta: Seção 9 (páginas legais), Seção 12 (conta de recebimento). Dados: chave única privacy.legal_entity em settings (Seção 26.8.1), do tipo JSON, com os campos razaoSocial, cnpj e endereco.
• Padrão: os campos são preenchidos no seed com os dados reais da empresa antes do primeiro deploy de produção. Em ambientes local e de homologação, o padrão é Palavra Diária Conteúdo Digital LTDA, CNPJ 00.000.000/0001-00 e endereço fictício, claramente marcados como dados de teste. Regra dura: o deploy de produção falha na verificação de sanidade descrita na Seção 25 se qualquer campo de privacy.legal_entity ainda estiver com valor de teste.

1.21 Q19 — Canal de suporte e SLA #

• Pergunta: qual o e-mail de suporte e qual o prazo prometido?
• Por que importa: o prazo aparece na página de planos como diferencial do plano pago e vira promessa contratual.
• Onde impacta: Seção 9 (comparativo de planos), Seção 13 (entitlements), Seção 19 (respostas automáticas). Dados: chave support.email em settings (Seção 26.8.1). O prazo prometido não é uma chave de configuração: ele é texto aprovado da Seção 10 e valor da matriz de entitlements da Seção 13.
• Padrão: suporte@palavradiaria.com.br. Plano gratuito: FAQ e e-mail sem prazo prometido. Plano pago: resposta em 1 dia útil. O robô do WhatsApp não faz atendimento humano; ele responde com o FAQ e encaminha o contato por e-mail.

1.22 Q20 — Idioma da interface administrativa #

• Pergunta: o painel administrativo fica em português ou em inglês?
• Por que importa: o painel do assinante é obrigatoriamente em português. O painel administrativo é usado por editores brasileiros, mas manter dois idiomas dobra o custo de texto.
• Onde impacta: Seção 15 (painel administrativo), Seção 5.14 (arquivo único de textos).
• Padrão: português do Brasil em toda a interface, incluindo o painel administrativo. Rótulos de dados técnicos que espelham valores do sistema (nomes de estado, códigos de erro da Meta, identificadores) permanecem em inglês, exatamente como são gravados, e ganham um texto explicativo em português ao lado. Não há alternância de idioma no MVP.

1.23 Q21 — Provedor de e-mail transacional e domínio remetente #

• Pergunta: qual serviço envia e-mails e de qual domínio?
• Por que importa: e-mail é canal secundário — recibo, magic link de acesso alternativo, aviso de falha de pagamento. Sem SPF, DKIM e DMARC configurados, esses e-mails vão para spam e o assinante perde o acesso alternativo.
• Onde impacta: Seção 8 (magic link), Seção 13 (avisos de cobrança), Seção 25 (registros DNS). Configuração: RESEND_API_KEY, EMAIL_FROM.
• Padrão: Resend, remetente Palavra Diária <nao-responda@palavradiaria.com.br>, com SPF, DKIM e DMARC em política quarantine no domínio de envio. Endereço de resposta apontando para o suporte de Q19.

1.24 Q22 — Provedor de armazenamento de mídia #

• Pergunta: onde ficam os arquivos de áudio?
• Por que importa: o áudio é o ativo mais caro de produzir. Perder o acervo significa regerar tudo e pagar TTS de novo.
• Onde impacta: Seção 16 (pipeline de mídia), Seção 25 (backup). Configuração: S3_ENDPOINT, S3_BUCKET, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY.
• Padrão: qualquer serviço compatível com S3, acessado pelo SDK oficial da AWS para S3 (ver Seção 4). Padrão operacional: bucket privado em provedor com egresso gratuito ou barato, chaves no formato devotionals/{YYYY}/{MM}/{devotionalId}/{voice}.{ext}, URLs assinadas com validade de 15 minutos para o player web. Armazenamento em disco local do servidor é explicitamente rejeitado, porque impede restaurar o serviço em outra máquina.

1.25 Q23 — Região de hospedagem #

• Pergunta: o servidor fica no Brasil ou fora?
• Por que importa: latência para o assinante, custo do servidor e leitura de conforto regulatório. A LGPD não exige hospedagem no país, mas hospedar no Brasil elimina a necessidade de justificar transferência internacional na política de privacidade.
• Onde impacta: Seção 22 (transferência internacional), Seção 25 (provisionamento).
• Padrão: região no Brasil (São Paulo) para o servidor de aplicação e o banco. O armazenamento de mídia pode ficar fora do país, desde que a política de privacidade declare a transferência e o bucket permaneça privado. Backups replicados para uma segunda região, sempre cifrados.

1.26 Q24 — Janela de manutenção #

• Pergunta: em que horário são aplicadas migrações e reinícios planejados?
• Por que importa: manutenção durante o planejamento ou o disparo do lote diário faz o produto quebrar sua única promessa.
• Onde impacta: Seção 25 (deploy), Seção 23 (silenciamento de alertas), Seção 27 (runbooks).
• Padrão: terças e quintas, das 14:00 às 16:00 (America/Sao_Paulo). Nenhum deploy planejado entre 05:00 e 08:00 em qualquer dia. Correções de emergência são permitidas a qualquer hora, com registro no diário de incidentes.

1.27 Q25 — Canal de alertas operacionais #

• Pergunta: para onde vão os alertas de falha?
• Por que importa: alerta que ninguém lê é alerta inexistente. O produto tem um único momento crítico por dia e precisa de aviso ativo se ele falhar.
• Onde impacta: Seção 23 (observabilidade e alertas), Seção 27 (runbooks). Configuração: OPS_WEBHOOK_URL e OPS_WEBHOOK_SECRET (Seção 26.3).
• Padrão: webhook de entrada em um grupo dedicado do Telegram ou do Slack, com duplicação por e-mail para o endereço de plantão em alertas de severidade crítica. O canal recebe também um resumo diário do lote às 06:30, mesmo quando tudo dá certo — silêncio absoluto impede distinguir "sem problema" de "monitoramento quebrado".

1.28 Q26 — Palavras-chave de saída e de retorno #

• Pergunta: quais palavras o assinante pode enviar para sair, e qual para voltar?
• Por que importa: reconhecer o pedido de saída é obrigação regulatória e de política da Meta. Falhar nisso derruba a qualidade do número.
• Onde impacta: Seção 19 (fluxos conversacionais), Seção 20 (opt-out). Dados: chaves send.optout_keywords e send.optin_keywords em settings (Seção 26.8.1).
• Padrão: saída por sete palavras — SAIR, PARAR, PARE, CANCELAR, STOP, DESCADASTRAR ou REMOVER; retorno por VOLTAR, RETORNAR, QUERO VOLTAR ou REATIVAR. A normalização canônica é a função normalizeKeyword() da Seção 20.3.2, que remove acentos e pontuação, colapsa espaços e compara em maiúsculas; nenhuma seção reimplementa essa regra. A comparação exige correspondência da mensagem inteira, não de um trecho. Exemplo: " sair, por favor " não é reconhecido como saída porque a mensagem inteira não corresponde à palavra, e cai no fluxo de ajuda com um botão explícito de cancelamento; " Sair " é reconhecido. O reconhecimento das palavras de saída tem precedência absoluta sobre qualquer outro processamento de mensagem de entrada (Seção 19.5).

1.29 Q27 — Analytics de produto e cookies #

• Pergunta: haverá ferramenta de análise no site, e ela usa cookies?
• Por que importa: ferramenta com cookies exige banner de consentimento e mais texto legal. Sem cookies, o banner deixa de ser necessário.
• Onde impacta: Seção 21 (analytics), Seção 22 (cookies e consentimento).
• Padrão: análise sem cookies e sem identificador persistente, auto-hospedada, com agregação por página e origem. Nesse desenho o site exibe apenas um aviso informativo, não um banner de consentimento com bloqueio. Se o dono do produto quiser uma ferramenta baseada em cookies, o banner com bloqueio prévio passa a ser obrigatório.

1.30 Q28 — Retenção de registros de mensagem #

• Pergunta: por quanto tempo guardar o histórico de mensagens enviadas e recebidas?
• Por que importa: o volume de registros de mensagem cresce mais rápido que qualquer outra tabela. Retenção longa aumenta custo de banco e de backup; retenção curta destrói a capacidade de investigar disputas de entrega.
• Onde impacta: Seção 6 (particionamento e expurgo), Seção 22 (retenção e anonimização). Dados: chave privacy.message_log_retention_months em settings (Seção 26.8.1).
• Padrão: 18 meses para registros de mensagem, com partição mensal e expurgo automático da partição mais antiga. Registros de consentimento e de eventos de pagamento têm retenção de 5 anos, por obrigação legal e fiscal, e não seguem esta chave. Backups têm retenção própria de 35 dias.

1.31 Tabela-resumo — Pergunta, Padrão e Onde muda #

Toda chave citada na coluna "Onde muda" segue o formato grupo.chave e existe no catálogo canônico da Seção 26.8.1 e no seed obrigatório da Seção 6.32.4. Nenhuma outra grafia é aceita: nome em maiúsculas é variável de ambiente (Seção 26.3), não chave de settings.

1.32 O que esta seção não permite mudar #

As decisões abaixo estão travadas e não são configuráveis. Alterá-las é mudança de escopo, com novo planejamento:

• Identidade do assinante é o número de telefone em E.164 (Seção 8).
• Não há período de carência em caso de falha de pagamento (Seção 13).
• Existem exatamente dois níveis de acesso, gratuito e pago, sem plano intermediário e sem teste gratuito (Seção 13).
• O áudio nunca é enviado como primeira mensagem do dia, por restrição da plataforma (Seção 17 e Seção 18).
• O conteúdo é escrito por um editor humano; não há geração de devocional por inteligência artificial no MVP (Seção 2.7).
• Fuso operacional único, sem horário personalizado por assinante (Seção 18).

2. Visão Geral do Produto e Objetivos #

2.1 O problema #

O cristão brasileiro médio quer começar o dia com uma leitura devocional e não consegue manter o hábito. Três causas se repetem:

1. Atrito de acesso. O devocional impresso fica na estante, o aplicativo devocional fica na terceira tela do celular e as notificações são silenciadas junto com todas as outras.
2. Ausência de horário. Sem um gatilho externo em horário fixo, a leitura compete com o despertador, o trânsito e o trabalho — e perde.
3. Formato único. Quem dirige, cozinha ou cuida de filhos às 6h da manhã não consegue ler. Precisa ouvir. A maioria das soluções entrega só texto.

O resultado é um padrão conhecido: a pessoa baixa o aplicativo, usa por quatro dias e abandona. O problema não é falta de conteúdo — conteúdo devocional é abundante e gratuito. O problema é entrega no lugar certo, na hora certa, no formato que cabe na rotina.

2.2 Proposta de valor #

Palavra Diária entrega o devocional dentro do WhatsApp, todos os dias às 6h da manhã, em texto e em áudio narrado. Não há aplicativo para instalar, conta para criar em outro lugar, nem notificação nova para ignorar. A mensagem chega no mesmo lugar onde a pessoa já conversa com a família.

Três afirmações resumem a promessa:

• Chega sozinho. O assinante não precisa lembrar de abrir nada.
• Cabe na rotina. Texto para quem pode ler, áudio de três a seis minutos para quem só pode ouvir.
• Sai quando quiser. Uma palavra no WhatsApp encerra o envio, sem formulário e sem ligação de retenção.

O plano gratuito existe para provar a promessa: um devocional em texto por semana, aos domingos. O plano pago entrega todos os dias, com áudio e acervo completo. A conversão acontece porque a diferença é sentida no cotidiano, não porque um recurso foi bloqueado artificialmente.

2.3 Público-alvo #

O produto atende dois perfis de comprador. Eles têm a mesma fé e rotinas opostas, e por isso justificam os dois formatos de entrega.

2.3.1 Persona 1 — Regina, 52 anos, auxiliar administrativa (Belo Horizonte/MG) #

• Rotina: acorda às 5h30, prepara o café, sai de casa às 6h40. Usa WhatsApp o dia inteiro, principalmente em grupos de família e da igreja. Instala poucos aplicativos e desconfia de cadastro que pede muitos dados.
• Relação com o conteúdo: frequenta a igreja há vinte anos, tem o hábito de "leitura da manhã" e sente culpa quando fica dias sem ler. Prefere ler a ouvir.
• Por que assina: valoriza o acervo e o hábito diário. Encaminha o devocional para o grupo da família quase todo dia, o que torna a persona também um canal de aquisição.
• Como paga: PIX. Tem cartão de crédito, mas evita usar em serviços recorrentes por receio de esquecer de cancelar.
• O que a faz cancelar: mensagens demais, tom sensacionalista ou promessa de prosperidade.
• Consequência de projeto: o texto completo precisa ser legível e encaminhável no WhatsApp, sem depender de link. A cobrança por PIX precisa ser um caminho de primeira classe, com lembretes antes do vencimento (Seção 12).

2.3.2 Persona 2 — Tiago, 34 anos, motorista de aplicativo (Guarulhos/SP) #

• Rotina: começa a rodar às 5h50. Fica com as mãos ocupadas e os olhos na rua até o meio da tarde. Consome quase tudo em áudio e vídeo.
• Relação com o conteúdo: vai à igreja aos domingos, ouve pregação em áudio no carro. Nunca terminou um plano de leitura escrito.
• Por que assina: o áudio. É a única forma de consumo compatível com o trabalho dele.
• Como paga: cartão de crédito, débito automático, sem pensar no assunto de novo.
• O que o faz cancelar: áudio robótico demais, longo demais ou que não abre no player do WhatsApp.
• Consequência de projeto: o áudio precisa chegar como mensagem de voz nativa, com player e forma de onda, e não como arquivo anexo. Isso determina o formato de codificação (Seção 16) e o desenho de entrega em duas etapas (Seção 18).

As duas personas convergem em um ponto decisivo: nenhuma das duas quer instalar mais um aplicativo. Esse é o eixo do produto, tratado em 2.8.

Os perfis internos que operam o sistema — editor de conteúdo, administrador e proprietário — são detalhados na Seção 3, junto com a matriz de permissões.

2.4 A jornada do assinante #

Em texto corrido: a pessoa chega à página de vendas por indicação, busca ou compartilhamento de um devocional encaminhado. Informa nome e telefone, marca o aceite de consentimento e recebe um código de seis dígitos no WhatsApp. Ao confirmar o código, a conta é criada no plano gratuito e o sistema envia uma mensagem de boas-vindas pedindo confirmação explícita de recebimento. Enquanto essa confirmação não vier, nenhum devocional é enviado. Confirmado o opt-in, o assinante entra na lista do próximo domingo.

No domingo às 6h, o sistema envia o convite do dia. O assinante toca no botão para ler e ouvir, e recebe o texto completo. Se estiver no plano gratuito, não recebe áudio, e a mensagem de fechamento informa que o áudio e os envios diários fazem parte do plano pago. Ao decidir assinar, ele abre o painel, escolhe mensal ou anual, escolhe cartão ou PIX e conclui o pagamento. A confirmação do pagamento chega por webhook, o acesso pago é liberado na hora e o envio diário começa no dia seguinte.

A partir daí, o ciclo é diário: convite às 6h, texto completo e áudio quando o assinante interage, e acervo disponível no painel a qualquer momento. Se o assinante já tiver conversado com o número nas últimas 24 horas, o sistema pula o convite e entrega o pacote completo diretamente — caminho mais barato e com menos atrito. Se o pagamento falhar, o acesso pago é revogado no mesmo instante e o assinante volta ao ritmo semanal, sem período de tolerância. Se ele pedir para sair, os envios param imediatamente e a cobrança do ciclo seguinte é suspensa na hora — mas a assinatura não é cancelada de imediato, para que um "SAIR" acidental não destrua a contratação. O painel deixa a distinção explícita: parar mensagens e encerrar a assinatura são ações separadas. Se em 30 dias não houver reativação, a assinatura é encerrada ao fim do período já pago, com aviso. A regra completa está na Seção 13.

 [Descoberta]                    [Cadastro]                     [Ativação]
 indicação, busca,     ┌────────────────────────────┐   ┌──────────────────────────┐
 devocional            │ nome + telefone + aceite   │   │ código de 6 dígitos no   │
 encaminhado  ───────► │ LGPD na página de vendas   ├──►│ WhatsApp (10 min de TTL) │
                       └────────────────────────────┘   └────────────┬─────────────┘
                                                                     │
                       ┌─────────────────────────────────────────────▼─────────────┐
                       │ boas-vindas no WhatsApp + confirmação ativa de opt-in     │
                       │ nenhum devocional sai antes desta confirmação             │
                       └─────────────────────────────┬────────────────────────────-┘
                                                     │
                                        ┌────────────▼────────────┐
                                        │  PLANO GRATUITO         │
                                        │  domingo 06:00, texto   │
                                        │  acervo de 7 dias       │
                                        └───┬─────────────────┬───┘
                                            │                 │
                       decide assinar ◄─────┘                 └────► segue gratuito
                              │                                      (sem prazo)
                 ┌────────────▼─────────────┐
                 │ checkout: mensal|anual   │
                 │ cartão (recorrente)      │
                 │ ou PIX (ciclo a ciclo)   │
                 └────────────┬─────────────┘
                              │  webhook de pagamento confirmado
                 ┌────────────▼─────────────┐
                 │  PLANO PAGO              │
                 │  todo dia 06:00          │
                 │  texto + áudio narrado   │
                 │  acervo completo         │
                 └────────────┬─────────────┘
                              │
        ┌─────────────────────┼─────────────────────┬───────────────────────┐
        │                     │                     │                       │
  falha de pagamento   cancela no painel      pede SAIR              permanece ativo
        │                     │                     │                       │
  revogação imediata   acesso até o fim do    envios param na hora;    renovação
  → volta ao gratuito  ciclo já pago →        cobrança do ciclo        automática
  (sem carência)       depois gratuito        seguinte suspensa;       a cada ciclo
                                              encerra em 30 dias
                                              sem reativação

2.5 O que é o MVP #

Está dentro do MVP, e nada aqui é opcional:

1. Página de vendas pública, com amostra de áudio e comparativo de planos.
2. Cadastro por telefone com código de acesso entregue no WhatsApp, opt-in em duas etapas e registro imutável de consentimento.
3. Dois níveis de acesso: gratuito semanal em texto e pago diário com texto e áudio.
4. Painel do assinante: acervo, dados cadastrais, reenvio do devocional do dia, gestão da assinatura, exportação dos próprios dados e exclusão da conta.
5. Painel administrativo: calendário editorial, editor de devocional, fluxo de publicação, revisão de áudio, gestão de assinantes, gestão de usuários internos e trilha de auditoria.
6. Pipeline de áudio: geração por síntese de voz, transcodificação para mensagem de voz, armazenamento em bucket privado e envio único de mídia ao canal.
7. Motor de envio diário com planejamento antecipado, controle de taxa, idempotência, registro de estado por mensagem, reprocessamento seguro e reavaliação do nível de acesso no instante do disparo, e não no planejamento.
8. Integração de pagamentos com criação de cliente, assinatura recorrente por cartão, cobrança por PIX, tratamento de webhooks e reconciliação diária.
9. Ciclo de vida da assinatura com revogação imediata em caso de falha de pagamento.
10. Opt-out por palavra-chave, reativação e a separação explícita entre parar mensagens e cancelar cobrança.
11. Dashboard de métricas com as definições da Seção 21.
12. Observabilidade: logs estruturados, métricas, alertas e runbooks para os modos de falha conhecidos.
13. Conformidade com a LGPD: base legal declarada, direitos do titular atendidos por autoatendimento, retenção definida e encarregado indicado.

2.6 Definição de sucesso #

Metas para os primeiros doze meses de operação. Cada métrica tem definição formal e fórmula na Seção 21; aqui estão apenas os alvos.

Exemplo numérico do alvo de custo: com preço mensal de R$ 19,90 e custo por assinante pago de R$ 3,00, a margem bruta por assinante é de R$ 16,90, ou 85%. Se a categoria do template diário for reclassificada e o custo por mensagem subir de forma relevante, o gatilho de revisão de preço é o custo mensal por assinante ultrapassar R$ 5,00 — não antes.

2.7 Fora de escopo #

Esta seção é a dona da lista. Nenhum item abaixo é especificado, projetado, prototipado ou "deixado preparado" em qualquer outra seção. Tentativa de implementar qualquer um deles é desvio de escopo e deve ser rejeitada pelo executor.

1. Telegram, e-mail ou SMS como canal de entrega do devocional. E-mail existe somente como canal transacional secundário (recibo, acesso alternativo, aviso de cobrança).
2. Multi-idioma. O produto é apenas em português do Brasil, interface e conteúdo.
3. Recursos sociais entre assinantes. Sem comentários, sem curtidas, sem seguir.
4. Horário de envio personalizado por assinante. Fuso e horário são únicos.
5. Narração humana gravada. Toda narração é sintetizada.
6. Multi-tenant ou white-label para outras igrejas. Uma marca, uma base.
7. Geração de devocional por inteligência artificial. O autor é humano, sempre.
8. Aplicativo móvel nativo. Nem Android, nem iOS, nem aplicativo web instalável com notificações próprias.
9. Pedidos de oração, aconselhamento ou qualquer atendimento pastoral.
10. Grupos e comunidades do WhatsApp. A entrega é individual, um a um.
11. Boleto bancário como forma de pagamento.
12. Emissão automática de nota fiscal.
13. Cupons, campanhas promocionais e descontos. Não existe tabela de cupons no modelo de dados, e nenhuma seção pode criá-la.
14. Testes A/B de conteúdo devocional.

2.8 Por que WhatsApp e não aplicativo próprio #

A escolha do canal é a decisão de produto mais importante, e é anterior a qualquer decisão técnica. O raciocínio:

A favor do WhatsApp

• Distribuição pronta. As duas personas já usam o aplicativo várias horas por dia. Não há passo de instalação, e o passo de instalação é onde a maioria dos funis morre.
• Entrega ativa e confiável. Mensagem no WhatsApp é lida. Notificação push de aplicativo novo é silenciada, agrupada ou bloqueada pelo sistema de economia de bateria, cenário comum em aparelhos Android de entrada.
• Áudio nativo. O canal já reproduz mensagens de voz com player e forma de onda, em velocidade ajustável, sem que seja preciso escrever um reprodutor.
• Compartilhamento embutido. Encaminhar um devocional para o grupo da família é um gesto de um toque. Isso vira aquisição orgânica sem custo.
• Custo de construção. Um aplicativo nativo em duas plataformas exigiria ciclos de revisão de loja, distribuição de versões e suporte a aparelhos antigos. O canal remove tudo isso.

Contra o WhatsApp, e como o projeto responde

Decisão registrada: o WhatsApp é o canal de entrega; o painel web é a superfície de gestão. Um aplicativo próprio não entra no roteiro enquanto a base for inferior a 50.000 assinantes, porque o custo de aquisição de instalação supera o ganho marginal de controle.

2.9 Contexto de mercado brasileiro #

As afirmações abaixo são premissas de trabalho adotadas no planejamento. Elas orientam prioridade, não substituem pesquisa própria.

• Onipresença do canal. O WhatsApp está instalado em praticamente todos os smartphones brasileiros em uso e é, para boa parte da população, sinônimo de "internet". Para o público das personas, é o primeiro aplicativo aberto de manhã e o último fechado à noite. Nenhum outro canal digital tem esse alcance no país.
• Pagamento instantâneo como padrão. O PIX se consolidou como meio de pagamento cotidiano e é frequentemente preferido ao cartão, sobretudo em faixas de renda média e para valores baixos. Ignorar o PIX em um produto de R$ 19,90 elimina uma parcela relevante de compradores dispostos. Em contrapartida, PIX não tem recorrência automática: cada ciclo exige uma cobrança nova e um lembrete. Isso é custo operacional aceito conscientemente.
• Fragilidade do cartão recorrente. No Brasil, cartões negados, limites baixos e trocas de cartão produzem churn involuntário significativo. O plano anual e o PIX são as duas respostas do produto a esse fato.
• Público cristão numeroso e com hábito de consumo de conteúdo religioso. Uma parcela expressiva da população brasileira se declara evangélica ou católica praticante, e o consumo diário de conteúdo religioso por rádio, vídeo e mensagens já é um comportamento estabelecido. O produto não precisa criar o hábito de consumo — precisa capturar um hábito existente e dar a ele horário e formato.
• Disposição a pagar por conteúdo devocional. Existe precedente de assinatura paga em aplicativos devocionais e em plataformas de conteúdo cristão. O ponto de preço de R$ 19,90/mês fica na faixa de assinaturas de baixo valor com as quais o público já convive, e o plano anual de R$ 199,00 reduz a fricção mensal.
• Sensibilidade de tom. O público reage mal a linguagem de venda agressiva, promessa de prosperidade e uso de culpa. O tom aprovado do produto está na Seção 10 e é uma decisão de produto, não de estilo.
• Custo de mensagens. O preço por mensagem iniciada pelo negócio varia por categoria e é revisado periodicamente pela plataforma. O desenho de entrega em duas etapas existe em boa parte para tornar o custo por assinante previsível mesmo se a categoria mudar. As duas faixas de custo consideradas estão na Seção 17.

2.10 Premissas de negócio #

2.11 Riscos de produto e mitigação #

3. Personas, Papéis e Matriz de Permissões #

3.1 Enum canônico de papéis #

O sistema tem exatamente quatro papéis. A lista é fechada. Nenhuma outra seção pode introduzir um quinto papel, e nenhuma funcionalidade pode depender de um papel que não esteja aqui.

// packages/core/src/auth/roles.ts
export const ROLES = ['SUBSCRIBER', 'EDITOR', 'ADMIN', 'OWNER'] as const
export type Role = (typeof ROLES)[number]

/** Ordem de precedência. Índice maior nunca é menos poderoso que índice menor. */
export const ROLE_RANK: Record<Role, number> = {
  SUBSCRIBER: 0,
  EDITOR: 1,
  ADMIN: 2,
  OWNER: 3,
}

/** Papéis que existem dentro do painel administrativo. */
export const STAFF_ROLES = ['EDITOR', 'ADMIN', 'OWNER'] as const satisfies readonly Role[]
export type StaffRole = (typeof STAFF_ROLES)[number]

O tipo enumerado correspondente é declarado no banco na Seção 6, com o mesmo nome e os mesmos valores. SUBSCRIBER nunca aparece como papel de usuário interno: a restrição é aplicada por CHECK constraint na tabela de usuários internos (Seção 6).

Nível de acesso é coisa diferente de papel. Todo assinante tem papel SUBSCRIBER; o que distingue gratuito de pago é o nível de acesso (FREE ou PAID), resolvido pela função resolveEntitlements(subscriber) descrita na Seção 13. Nenhum código pode inferir capacidades a partir do papel para assinantes, nem a partir do nível de acesso para usuários internos.

3.2 Como cada papel nasce e como morre #

Não existe autocadastro de usuário interno. Não existe rota pública que crie um registro em admin_users. A única exceção é o seed de instalação, que cria um único OWNER a partir de variáveis de ambiente e exige troca de senha no primeiro acesso.

3.3 Persona operacional — Assinante gratuito #

• Quem é: pessoa cadastrada, com opt-in confirmado, sem assinatura paga ativa.
• O que faz: recebe o devocional semanal aos domingos às 06:00; abre o painel para ler o acervo dos últimos 7 dias; pede um reenvio por dia; edita nome e e-mail; exporta seus próprios dados; exclui a própria conta; assina um plano pago.
• O que não pode fazer: receber áudio; receber devocional em dias que não sejam o dia do envio gratuito; abrir devocionais fora da janela de acervo; pedir mais de um reenvio no mesmo dia; ver dados de qualquer outro assinante; acessar qualquer rota do painel administrativo.
• Cenário concreto: em uma quarta-feira, Regina abre o painel e clica em "reenviar devocional de hoje". O sistema responde NO_DEVOTIONAL_FOR_TODAY_ON_FREE_TIER, porque no nível gratuito o dia corrente não tem devocional atribuído a ela. O painel exibe o convite para assinar, com o texto aprovado na Seção 10.

3.4 Persona operacional — Assinante pago #

• Quem é: assinante com assinatura em estado ativo e nível de acesso PAID.
• O que faz: tudo do gratuito, mais: recebe devocional todos os dias; recebe áudio narrado; acessa o acervo completo desde a primeira assinatura paga (Seção 13.6.1); pede até três reenvios por dia; troca de plano mensal para anual; troca a forma de pagamento; consulta recibos; cancela a assinatura.
• O que não pode fazer: pausar a assinatura mantendo o acesso; escolher outro horário de envio; escolher outra voz de narração; baixar o arquivo de áudio fora do player do painel por URL permanente — as URLs são assinadas e expiram em 15 minutos (Seção 16).
• Cenário concreto: Tiago cancela no dia 10, com ciclo pago até o dia 28. Ele continua recebendo áudio até o dia 28 e é rebaixado para gratuito na virada do dia 29. Isso não é período de carência; é o período que ele já pagou. A distinção é normativa e está na Seção 13.

3.5 Persona interna — Editor de conteúdo (EDITOR) #

• Quem é: responsável pela produção do devocional. Perfil editorial, não técnico.
• O que faz: cria devocionais; edita rascunhos; preenche título, referência bíblica, texto do versículo, versão da tradução, reflexão, oração e teaser; agenda a data de publicação no calendário editorial; marca o devocional como pronto, o que dispara a geração de áudio; ouve o áudio gerado; solicita nova geração de áudio; publica o devocional; consulta o histórico de revisões e restaura uma revisão anterior.
• O que não pode fazer: ver telefone, CPF, e-mail ou qualquer dado pessoal de assinante; ver dados de pagamento; alterar preços; criar, editar ou desativar usuários internos; alterar configurações do sistema; ligar ou desligar feature flags; exportar bases de assinantes; disparar reenvio para um assinante específico; alterar templates do canal de mensageria; acessar a trilha de auditoria.
• Cenário concreto: o editor abre a lista de assinantes por curiosidade. A rota retorna 403 com code FORBIDDEN_ROLE, e o evento é registrado com o identificador do usuário, a rota e o papel exigido. Tentativas repetidas geram alerta operacional (Seção 23).

3.6 Persona interna — Administrador (ADMIN) #

• Quem é: responsável pela operação diária do serviço.
• O que faz: tudo do editor, mais: consulta e edita cadastro de assinantes; consulta assinaturas, pagamentos e eventos de pagamento; força a reconciliação de uma assinatura específica contra a operadora de pagamentos; dispara reenvio manual para um assinante; consulta lotes de envio, tentativas de entrega e registros de mensagem; reprocessa um lote com falha; consulta mensagens recebidas; gerencia templates do canal de mensageria; consulta o dashboard de métricas; exporta relatórios; cria e desativa EDITOR; consulta a trilha de auditoria; consulta execuções de job e entregas de webhook.
• O que não pode fazer: criar, promover, rebaixar ou desativar ADMIN ou OWNER; alterar preços dos planos; alterar chaves de integração; excluir permanentemente assinantes ou devocionais; alterar registros de consentimento; alterar a trilha de auditoria; alterar configurações marcadas como sensíveis (lista em 3.9).
• Cenário concreto: um assinante liga dizendo que não recebeu o devocional. O administrador abre a ficha, vê que a última tentativa de entrega falhou com um código de limitação de entrega do canal, e usa o botão de reenvio manual. A ação é registrada na trilha de auditoria com o identificador do assinante e o motivo informado.

3.7 Persona interna — Proprietário (OWNER) #

• Quem é: responsável final pelo negócio e pelos dados. Tipicamente uma ou duas pessoas.
• O que faz: tudo do administrador, mais: cria, promove, rebaixa e desativa usuários internos de qualquer papel; altera preços e cria novas versões de plano; altera configurações sensíveis; aciona a exclusão definitiva de um assinante a pedido do titular; aprova e executa exportações completas de base; visualiza custos e chaves de integração em forma mascarada; encerra sessões de qualquer usuário.
• O que não pode fazer: nada além do sistema — mas continua sujeito a três limites invioláveis: (a) não pode remover ou rebaixar o último proprietário ativo (3.10); (b) não pode editar nem apagar registros de consentimento e a trilha de auditoria, que são somente-inserção; (c) não pode ler valores em texto claro de segredos de integração, que nunca são devolvidos pela API.
• Cenário concreto: o proprietário decide promover um editor a administrador. A operação exige reautenticação com o segundo fator, grava um registro de auditoria com papel anterior e novo papel, e revoga todas as sessões ativas do usuário afetado, forçando novo login com o papel atualizado.

3.8 Matriz de permissões — papel × recurso × ação #

Legenda: L ler · C criar · E editar · A apagar · X exportar · — nenhuma permissão · p apenas os próprios registros do usuário autenticado.

Onde consta A para assinantes e devocionais, entenda-se exclusão lógica; a exclusão física é feita apenas por rotina de retenção (Seção 22).

Esta tabela é a única fonte do papel mínimo de qualquer recurso. O inventário de rotas da Seção 7 e o mapa de telas da Seção 15 derivam dela e nunca a contradizem. Onde uma rota ou uma tela precisou de leitura própria, a resolução é esta, e vale como norma:

Regras que a tabela não expressa e que valem como norma:

1. Toda leitura marcada com p é filtrada no repositório pelo identificador do assinante contido na sessão, nunca por parâmetro vindo do cliente. Um assinante que troca o identificador na URL recebe 404 com code SUBSCRIBER_NOT_FOUND, e não 403 — para não confirmar a existência do registro alheio.
2. Nenhuma rota administrativa aceita filtro por telefone completo sem que o usuário tenha permissão de leitura de assinantes. Busca por telefone parcial exige ADMIN.
3. Exportações sempre geram registro na trilha de auditoria, com a quantidade de linhas exportadas e o filtro aplicado.
4. Configurações sensíveis são: chaves de integração, token de webhook, segredo de assinatura de sessão, dados da entidade jurídica e limites de taxa de envio. A API nunca devolve o valor em texto claro; devolve apenas os quatro últimos caracteres e um indicador de que o valor está preenchido.

3.9 Catálogo de permissões nomeadas #

A verificação de acesso no código nunca compara papéis diretamente em regra de negócio. Ela compara permissões nomeadas, e o mapa de papel para permissões é único.

// packages/core/src/auth/permissions.ts
export const PERMISSIONS = [
  'devotionals:read', 'devotionals:write', 'devotionals:publish', 'devotionals:delete',
  'audio:read', 'audio:regenerate',
  'templates:read', 'templates:write',
  'subscribers:read', 'subscribers:write', 'subscribers:delete', 'subscribers:export',
  'billing:read', 'billing:write', 'billing:reconcile',
  'delivery:read', 'delivery:resend', 'delivery:reprocess',
  'metrics:read', 'metrics:export',
  'staff:read', 'staff:write:editor', 'staff:write:any',
  'audit:read',
  'settings:read', 'settings:write', 'settings:write:sensitive',
  'flags:read', 'flags:write',
  'jobs:read', 'jobs:write',
] as const
export type Permission = (typeof PERMISSIONS)[number]

const EDITOR_PERMISSIONS: Permission[] = [
  'devotionals:read', 'devotionals:write', 'devotionals:publish',
  'audio:read', 'audio:regenerate',
  'templates:read', 'delivery:read', 'metrics:read',
  'settings:read', 'flags:read',
]

const ADMIN_PERMISSIONS: Permission[] = [
  ...EDITOR_PERMISSIONS,
  'devotionals:delete',
  'templates:write',
  'subscribers:read', 'subscribers:write', 'subscribers:delete', 'subscribers:export',
  'billing:read', 'billing:write', 'billing:reconcile',
  'delivery:resend', 'delivery:reprocess',
  'metrics:export', 'audit:read',
  'staff:read', 'staff:write:editor',
  'settings:write', 'flags:write',
  'jobs:read', 'jobs:write',
]

const OWNER_PERMISSIONS: Permission[] = [
  ...ADMIN_PERMISSIONS,
  'staff:write:any',
  'settings:write:sensitive',
]

export const ROLE_PERMISSIONS: Record<Role, readonly Permission[]> = {
  SUBSCRIBER: [], // assinante nunca usa permissões nomeadas; usa escopo próprio + entitlements
  EDITOR: EDITOR_PERMISSIONS,
  ADMIN: ADMIN_PERMISSIONS,
  OWNER: OWNER_PERMISSIONS,
}

export function can(role: Role, permission: Permission): boolean {
  return ROLE_PERMISSIONS[role].includes(permission)
}

Consequência prática: para descobrir se um administrador pode reprocessar um lote, o código pergunta can(session.role, 'delivery:reprocess'). Se amanhã a permissão migrar para OWNER, muda uma linha, e não vinte rotas. A aplicação dessa verificação nas rotas HTTP é descrita na Seção 8.

3.10 Escalonamento, rebaixamento e a regra do último proprietário #

Regras normativas, verificadas na camada de serviço e reforçadas por constraint no banco onde possível:

1. Ninguém promove a si mesmo. Se actor.id === target.id e o papel muda, a operação falha com CANNOT_CHANGE_OWN_ROLE.
2. Ninguém cria alguém acima de si. O papel alvo precisa ter posto menor ou igual ao do autor. Um ADMIN só cria e edita EDITOR. Tentativa de criar ADMIN falha com INSUFFICIENT_ROLE_TO_ASSIGN.
3. Ninguém edita alguém acima de si. Um ADMIN que tenta desativar um OWNER recebe INSUFFICIENT_ROLE_TO_ASSIGN. Um ADMIN que tenta editar outro ADMIN recebe o mesmo erro: papéis de mesmo posto não se administram, exceto no posto de proprietário.
4. Último proprietário é intocável. Não é possível rebaixar, desativar ou excluir um OWNER se ele for o único proprietário ativo. A verificação é feita dentro da mesma transação da alteração, com bloqueio de linha, e o erro é LAST_OWNER_PROTECTED.
5. Reautenticação obrigatória. Qualquer mudança de papel exige que o autor apresente novamente o segundo fator, dentro de uma janela de 5 minutos (Seção 8).
6. Revogação de sessão. Alterar o papel de um usuário revoga imediatamente todas as sessões ativas dele. O papel gravado na sessão nunca é atualizado no lugar.

// packages/core/src/staff/change-role.ts (trecho normativo)
export async function assertCanAssignRole(actor: StaffContext, targetRole: StaffRole) {
  if (ROLE_RANK[targetRole] > ROLE_RANK[actor.role]) {
    throw new AppError('INSUFFICIENT_ROLE_TO_ASSIGN', 403)
  }
  if (ROLE_RANK[targetRole] === ROLE_RANK[actor.role] && actor.role !== 'OWNER') {
    throw new AppError('INSUFFICIENT_ROLE_TO_ASSIGN', 403)
  }
}

/** Executada SEMPRE dentro da transação que altera o papel ou desativa o usuário. */
export async function assertNotLastOwner(tx: Tx, targetId: string) {
  const owners = await tx.$queryRaw<{ id: string }[]>`
    SELECT id FROM admin_users
    WHERE role = 'OWNER' AND deleted_at IS NULL AND is_active = true
    FOR UPDATE
  `
  if (owners.length <= 1 && owners.some((o) => o.id === targetId)) {
    throw new AppError('LAST_OWNER_PROTECTED', 409)
  }
}

Exemplo concreto de concorrência: dois proprietários, Ana e Bruno, tentam rebaixar um ao outro no mesmo segundo. As duas transações disputam o mesmo conjunto de linhas bloqueado por FOR UPDATE. A primeira a obter o bloqueio rebaixa o outro; a segunda, ao reexecutar a consulta, encontra um único proprietário ativo, que é o próprio alvo, e falha com LAST_OWNER_PROTECTED. Nunca existe estado com zero proprietários.

3.11 Trilha de auditoria de mudanças de papel #

Toda alteração de papel, criação de usuário interno, desativação e reativação grava um registro na trilha de auditoria (tabela admin_audit_log, definida na Seção 6). A trilha é somente-inserção: não há rota de edição nem de exclusão, e a permissão de escrita do banco para a aplicação não inclui UPDATE nem DELETE nessa tabela.

Campos gravados nas ações de papel:

Os nomes de coluna são os da Seção 6.9, que é a dona da definição física de admin_audit_log: não existem colunas actor_id, actor_admin_id, target_type nem target_id.

Exemplo de registro:

{
  "id": "aud_01J9Z8Q6M0Q2W7X3B4C5D6E7F8",
  "actorType": "ADMIN",
  "adminUserId": "adm_01J9Z0000000000000000OWNER",
  "actorRole": "OWNER",
  "action": "staff.role_changed",
  "entityType": "admin_user",
  "entityId": "adm_01J9Z1111111111111111EDITR",
  "before": { "role": "EDITOR", "isActive": true },
  "after": { "role": "ADMIN", "isActive": true },
  "reason": "Assume operação de suporte a partir de setembro.",
  "ip": "189.45.10.22",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
  "createdAt": "2026-08-25T13:41:07.882Z"
}

A trilha alimenta uma tela no painel administrativo com filtro por autor, por tipo de ação e por período, com exportação em CSV disponível para ADMIN e OWNER. Retenção: 5 anos, igual à dos registros de consentimento (Seção 22).

3.12 Casos de borda de autorização #

4. Arquitetura e Stack Tecnológica #

4.1 A arquitetura em um parágrafo #

Um monorepo com três aplicações e três pacotes compartilhados. A aplicação web serve a página de vendas, os dois painéis e todas as rotas HTTP, inclusive os webhooks. O worker executa tudo que é assíncrono ou agendado: planejar o lote do dia, gerar áudio, enviar mensagens, processar eventos de pagamento e reconciliar cobranças. A CLI de operação existe para semear, corrigir e reprocessar sem abrir o banco na mão. Postgres é a única fonte de verdade transacional; Redis é fila e cache, nunca fonte de verdade. Um único servidor com Docker Compose atende o alvo de escala do primeiro ano.

4.2 Stack canônica #

Esta seção é a dona de todas as versões de dependência do projeto. Nenhuma outra seção declara versão; todas referenciam esta tabela.

Ferramentas de desenvolvimento sem linha de versão fixada — instale a estável corrente no momento do build: ESLint com typescript-eslint, Prettier, eslint-plugin-import, eslint-plugin-jsx-a11y, commitlint com @commitlint/config-conventional, lefthook para hooks de Git, tsx para execução de scripts TypeScript e dotenv-cli.

Estas linhas de versão são um piso conhecido-bom, não um lockfile. No momento do build, instale a release estável corrente de cada dependência (pnpm add <pkg>@latest, ou o equivalente do ecossistema), confirme que a linha major ainda corresponde e deixe o lockfile registrar as versões exatas resolvidas.

O pnpm-lock.yaml é versionado e obrigatório. A integração contínua executa pnpm install --frozen-lockfile; divergência entre o manifesto e o lockfile reprova o build. Atualizações de dependência entram por commit próprio, com prefixo chore(deps).

4.3 Serviços externos e suas interfaces #

A versão da Graph API acima é o piso conhecido-bom. No momento do build, o executor confirma qual é a versão estável corrente aceita pelo endpoint e usa a mais nova, ajustando apenas a constante de versão no cliente tipado. Nenhuma outra parte do código conhece a versão.

4.4 Diagrama de componentes #

                       Internet
                          │
                 ┌────────▼─────────┐
                 │  Caddy (TLS,     │  palavradiaria.com.br
                 │  proxy reverso)  │  app.palavradiaria.com.br
                 └───┬──────────┬───┘  api.palavradiaria.com.br
                     │          │
        ┌────────────▼───┐   ┌──▼──────────────────┐
        │  apps/web      │   │ (mesma aplicação:    │
        │  Next.js       │   │  rotas /api/*        │
        │  ─ landing     │   │  e webhooks)         │
        │  ─ painel      │   └──┬──────────────────┘
        │    assinante   │      │
        │  ─ painel      │      │ grava evento cru + enfileira
        │    admin       │      │
        └───┬────────┬───┘      │
            │        │          │
            │        └──────────┼───────────────┐
            │                   │               │
      ┌─────▼─────────┐   ┌─────▼──────────┐    │
      │  PostgreSQL   │◄──┤   Redis         │    │
      │  fonte única  │   │  filas BullMQ   │    │
      │  de verdade   │   │  + cache leve   │    │
      └─────▲─────────┘   └─────▲──────────┘    │
            │                   │               │
            │             ┌─────┴───────────────▼────┐
            └─────────────┤  apps/worker             │
                          │  treze filas, Seção 18.8 │
                          │  ─ send.plan (05:40)     │
                          │  ─ send.dispatch         │
                          │  ─ send.followup         │
                          │  ─ whatsapp.inbound      │
                          │  ─ tts.generate          │
                          │  ─ media.upload          │
                          │  ─ billing.webhook       │
                          │  ─ billing.reconcile     │
                          │  ─ billing.lifecycle     │
                          │  ─ metrics.rollup        │
                          │  ─ maintenance.cleanup   │
                          │  ─ email.send            │
                          │  ─ messaging.pause       │
                          │  Fastify: /api/internal/health
                          │           /api/internal/metrics
                          └──┬───────┬───────┬───────┘
                             │       │       │
             ┌───────────────▼┐ ┌────▼─────┐ ┌▼──────────────────┐
             │ WhatsApp Cloud │ │ Asaas    │ │ TTS (ElevenLabs / │
             │ API (Meta)     │ │ API v3   │ │ Google) + S3      │
             └────────────────┘ └──────────┘ └───────────────────┘

             apps/ops  ── CLI executada sob demanda no host,
                          fala com Postgres, Redis e as integrações

A lista de filas acima é exatamente a da Seção 18.8, que é a dona: são treze, com nome único no formato dominio.acao. Nenhuma outra seção usa apelido ou variação. Não existe fila de mensagens mortas: um job que esgota as tentativas fica no estado failed da própria fila e grava uma linha em job_runs com status = 'DEAD', que é a dead-letter do sistema.

Regra de fronteira: somente o worker fala com o canal de mensageria e com o provedor de voz. A aplicação web nunca envia mensagem de forma síncrona dentro de uma requisição HTTP. Quando o painel pede um reenvio, ele enfileira um job e responde imediatamente. Isso mantém o p95 das rotas dentro da meta e evita que uma lentidão de terceiro derrube a interface.

4.5 Estrutura do monorepo #

palavra-diaria/
├── apps/
│   ├── web/                          # Next.js: público, painéis e API HTTP
│   │   ├── app/
│   │   │   ├── (marketing)/          # rotas públicas: /, /planos, /faq, /termos...
│   │   │   ├── (subscriber)/         # painel do assinante, exige sessão SUBSCRIBER
│   │   │   ├── (admin)/              # painel administrativo, exige sessão de equipe
│   │   │   ├── api/                  # route handlers; um arquivo route.ts por recurso
│   │   │   │   ├── public/
│   │   │   │   ├── auth/
│   │   │   │   ├── signups/
│   │   │   │   ├── sessions/
│   │   │   │   ├── me/
│   │   │   │   ├── devotionals/
│   │   │   │   ├── checkout/
│   │   │   │   ├── subscriptions/
│   │   │   │   ├── payments/
│   │   │   │   ├── admin/
│   │   │   │   ├── internal/         # health, ready, metrics, version
│   │   │   │   └── webhooks/         # asaas/route.ts, whatsapp/route.ts
│   │   │   ├── layout.tsx
│   │   │   └── not-found.tsx
│   │   ├── src/
│   │   │   ├── components/
│   │   │   │   ├── ui/               # primitivos shadcn/ui, sem regra de negócio
│   │   │   │   ├── marketing/
│   │   │   │   ├── subscriber/
│   │   │   │   └── admin/
│   │   │   ├── hooks/                # hooks de cliente, TanStack Query
│   │   │   ├── i18n/pt-BR.ts         # arquivo único de textos de interface
│   │   │   ├── legal/consent/        # versões do texto de consentimento
│   │   │   ├── lib/                  # http, formatadores, guards de sessão
│   │   │   └── styles/theme.css      # tokens de cor, tipografia e espaçamento
│   │   ├── public/
│   │   ├── middleware.ts             # roteamento por audiência de sessão
│   │   ├── next.config.ts
│   │   └── package.json
│   ├── worker/                       # processos assíncronos
│   │   ├── src/
│   │   │   ├── queues/               # definição de filas e opções de retry
│   │   │   ├── jobs/                 # um arquivo por fila; nome do arquivo = nome da fila
│   │   │   │   │                     # com ponto trocado por hífen (Seção 18.8)
│   │   │   │   ├── send-plan.ts
│   │   │   │   ├── send-dispatch.ts
│   │   │   │   ├── send-followup.ts
│   │   │   │   ├── whatsapp-inbound.ts
│   │   │   │   ├── tts-generate.ts
│   │   │   │   ├── media-upload.ts
│   │   │   │   ├── billing-webhook.ts
│   │   │   │   ├── billing-reconcile.ts
│   │   │   │   ├── billing-lifecycle.ts
│   │   │   │   ├── metrics-rollup.ts
│   │   │   │   ├── maintenance-cleanup.ts
│   │   │   │   ├── email-send.ts
│   │   │   │   └── messaging-pause.ts
│   │   │   ├── scheduler.ts          # registro dos jobs repetíveis com fuso
│   │   │   ├── http.ts               # Fastify: /api/internal/health, /api/internal/ready, /api/internal/metrics
│   │   │   └── main.ts
│   │   └── package.json
│   └── ops/                          # CLI de operação
│       ├── src/commands/             # seed, backfill, resend, health, template-sync
│       └── package.json
├── packages/
│   ├── db/                           # Prisma: schema, client, migrações, seeds
│   │   ├── prisma/
│   │   │   ├── schema.prisma
│   │   │   ├── migrations/
│   │   │   └── seed.ts
│   │   └── src/index.ts              # singleton do client + helpers de transação
│   ├── core/                         # domínio puro, sem I/O
│   │   └── src/
│   │       ├── auth/                 # papéis, permissões, contexto de sessão
│   │       ├── entitlements/         # resolveEntitlements e limites por nível
│   │       ├── subscription/         # máquina de estados da assinatura
│   │       ├── devotional/           # estados editoriais, teaser, roteiro de narração
│   │       ├── delivery/             # cálculo do lote, chaves de idempotência
│   │       ├── phone.ts              # normalização E.164 e variantes brasileiras
│   │       ├── errors.ts             # AppError e catálogo de códigos
│   │       ├── logger.ts             # fábrica pino e regras de redação
│   │       ├── schemas/              # Zod compartilhado entre web e worker
│   │       └── time.ts               # helpers de fuso America/Sao_Paulo
│   └── integrations/                 # clientes tipados de terceiros
│       └── src/
│           ├── whatsapp/             # provider, tipos, mapeamento de erros
│           ├── asaas/
│           ├── tts/                  # elevenlabs.ts, google.ts, provider.ts
│           ├── storage/              # cliente S3 e URLs assinadas
│           └── email/
├── docker/                           # Dockerfile.web, Dockerfile.worker, Caddyfile
├── .github/workflows/                # ci.yml, deploy.yml
├── docker-compose.yml
├── docker-compose.prod.yml
├── .env.example
├── pnpm-workspace.yaml
├── package.json                      # scripts raiz: dev, build, test, lint, typecheck
├── tsconfig.base.json
└── README.md

Decisão registrada: não há Turborepo, Nx ou qualquer orquestrador de build no MVP. Com três aplicações e três pacotes, os filtros nativos do gerenciador de pacotes (pnpm --filter web build) resolvem o problema sem adicionar uma camada de cache para manter. Se o tempo de build ultrapassar cinco minutos na integração contínua, a decisão é revista.

4.6 Responsabilidade de cada aplicação #

apps/web — superfície HTTP única. Serve HTML das páginas públicas e dos painéis, e expõe todas as rotas /api/*, incluindo os webhooks. Responsabilidades exclusivas: renderizar interface, validar entrada, autenticar e autorizar, escrever no banco o que é síncrono por natureza (cadastro, aceite de consentimento, criação de assinatura) e enfileirar tudo que é lento. Proibições: chamar o canal de mensageria; chamar o provedor de voz; executar transcodificação; rodar laços sobre a base inteira.

apps/worker — dono de todo trabalho assíncrono, agendado e de longa duração. Registra os jobs repetíveis com fuso America/Sao_Paulo, consome as filas, aplica limite de taxa, retries com espera exponencial e idempotência. Expõe um servidor HTTP interno mínimo com verificação de saúde e métricas, acessível apenas na rede interna do Compose. É o único processo com credenciais do canal de mensageria e do provedor de voz.

apps/ops — comandos de operação executados sob demanda: semear planos e usuário inicial, sincronizar templates com a plataforma, reprocessar um lote, reenviar para um assinante, recalcular métricas de um período, verificar saúde das integrações, exportar dados de um titular. Toda operação destrutiva exige confirmação explícita por argumento e grava registro na trilha de auditoria com autor ops-cli e o usuário do sistema operacional.

4.7 Responsabilidade de cada pacote #

packages/db — dono do schema e do acesso ao banco. Exporta o client singleton, o helper de transação e os tipos gerados. Contém as migrações e os seeds. Nenhuma aplicação instancia o client por conta própria; todas importam daqui, o que garante um único pool de conexões por processo.

packages/core — domínio puro, sem entrada e sem saída. Regras de nível de acesso, máquina de estados da assinatura, estados editoriais, normalização de telefone, cálculo do lote diário, chaves de idempotência, classe de erro, catálogo de códigos, fábrica de logger e todos os schemas Zod. Regra dura: este pacote não importa packages/db nem packages/integrations, não faz chamada de rede, não lê variável de ambiente e não usa relógio global sem receber o instante por parâmetro. Isso o torna testável sem infraestrutura e é o que permite que web e worker apliquem exatamente a mesma regra.

packages/integrations — clientes tipados de terceiros. Cada integração expõe uma interface e uma implementação. Traduz erros de terceiros para o catálogo de erros interno, aplica tempo limite, retry e registro estruturado. Nunca contém regra de negócio: decidir se uma mensagem deve ser enviada é do domínio; como enviar é daqui.

O grafo de dependências entre pacotes é acíclico e verificado por regra de lint:

core  ◄── db            core  ◄── integrations
  ▲                       ▲
  └────── web ────────────┘
  └────── worker ─────────┘
  └────── ops ────────────┘

4.8 Fluxos de ponta a ponta #

Os quatro caminhos abaixo são os que definem a arquitetura. O detalhamento de cada passo está nas seções donas; aqui interessa quem chama quem, o que é síncrono e onde está a fronteira transacional.

4.8.1 Cadastro e opt-in #

Navegador        apps/web            Postgres        Redis/Fila        worker          Canal
   │                │                   │               │                │              │
   │ POST /api/signups                  │               │                │              │
   ├───────────────►│ valida Zod        │               │                │              │
   │                │ normaliza telefone│               │                │              │
   │                │ (E.164 validado   │               │                │              │
   │                │  ANTES de cifrar) │               │                │              │
   │                ├── TX ────────────►│ subscriber (PENDING_VERIFICATION)             │
   │                │                   │ consent_event (append-only)    │              │
   │                │                   │ otp_code (hash, TTL 10 min)    │              │
   │                │◄── commit ────────┤               │                │              │
   │                ├───────────────────┼──────────────►│ send.dispatch  │              │
   │◄─ 202 {status} │                   │               ├───────────────►│ template     │
   │                │                   │               │                ├─────────────►│
   │ POST /api/signups/verifications    │               │                │              │
   ├───────────────►│ confere hash e tentativas         │                │              │
   │                ├── TX ────────────►│ marca telefone verificado      │              │
   │                │                   │ cria sessão (30 dias)          │              │
   │◄─ 200 + cookie │                   │               │                │              │
   │                │                   │               │ send.dispatch  │              │
   │                │                   │               ├───────────────►│ boas-vindas  │
   │                │                   │               │                ├─────────────►│
   │                │  (assinante responde SIM ou toca no botão)         │              │
   │                │  webhook de entrada ──────────────────────────────►│ whatsapp.    │
   │                │                   │                                │ inbound      │
   │                │                   │◄─ opt_in_confirmed_at ─────────┤              │
   │                │                   │  nível FREE, elegível ao envio │              │

Regra crítica: enquanto opt_in_confirmed_at for nulo, o assinante não entra em nenhum lote. O cadastro é reversível e não gera cobrança.

4.8.2 Pagamento e liberação do acesso #

Painel          apps/web           Asaas            Postgres         Fila          worker
  │                │                 │                 │              │              │
  │ POST /api/me/subscription        │                 │              │              │
  ├───────────────►│ valida CPF e plano                │              │              │
  │                ├── TX ──────────────────────────►  │ subscription (PENDING_PAYMENT)
  │                │◄─ commit ───────────────────────  │              │              │
  │                ├─ POST /v3/customers ──►│          │              │              │
  │                ├─ POST /v3/subscriptions ►│ externalReference = id nosso        │
  │                │◄─ id da assinatura ─────┤          │              │              │
  │◄─ 200 {checkout│ ou QR PIX}      │       │          │              │              │
  │                │                 │       │          │              │              │
  │        (assinante paga)          │       │          │              │              │
  │                │  POST /api/webhooks/asaas         │              │              │
  │                │◄────────────────┤ PAYMENT_CONFIRMED             │              │
  │                ├── TX ──────────────────────────►  │ payment_event (dedupe por id)
  │                ├───────────────────────────────────┼─────────────►│ billing.webhook
  │                ├─ 200 em < 2 s ─►│       │          │              │              │
  │                │                 │       │          │              ├── TX ───────►│
  │                │                 │       │  subscription ACTIVE + tier PAID       │
  │                │                 │       │  subscription_event + payment          │
  │                │                 │       │          │              │  notifica canal

O handler do webhook faz o mínimo: autentica, persiste o evento cru, enfileira e responde. Todo o efeito colateral acontece no worker, de forma idempotente por identificador de evento. O motivo é operacional: a operadora pausa a fila de webhooks após falhas consecutivas, e um handler lento vira uma falha. Pela mesma razão, corpo inválido nunca produz resposta não-2xx: autenticado o remetente, qualquer falha posterior responde 200 e é persistida para reprocessamento, conforme a Seção 7.15.1. A única exceção é 413 para corpo acima do limite, medido antes da leitura.

4.8.3 Envio diário #

05:40  scheduler (job repetível, fuso nomeado America/Sao_Paulo)
   │
   ├─► send.plan  ── chave de idempotência plan:{data}
   │      ├─ carrega devocional publicado da data
   │      ├─ se não houver → alerta crítico e encerra sem enviar
   │      ├─ seleciona destinatários:
   │      │    PAID  → todos com opt-in confirmado e sem opt-out
   │      │    FREE  → somente no dia do envio gratuito
   │      ├─ cria send_batch + uma delivery_attempt por assinante
   │      └─ enfileira send.dispatch com atraso até 06:00
   │
06:00  send.dispatch (limite de 20 mensagens por segundo)
   │      ├─ RELÊ o assinante por chave primária, imediatamente antes de chamar
   │      │  o provedor: deleted_at, blocked_at, opt_out_at e tier
   │      │     deleted_at/blocked_at → encerra como SKIPPED_INELIGIBLE
   │      │     opt_out_at            → encerra como SKIPPED_OPTED_OUT
   │      │     tier FREE em item planejado como PAID → rebaixa na hora,
   │      │        entrega só o texto, nunca o áudio
   │      ├─ janela de conversa aberta?
   │      │     sim → envia texto completo; se PAID, envia áudio; envia fechamento
   │      │     não → envia template de convite com dois botões
   │      ├─ grava message_log (status inicial: sent)
   │      └─ erro conhecido do canal → política própria por código (Seção 27)
   │
06:00+ webhooks de status ─► whatsapp.inbound ─► atualiza message_logs
   │
06:30  resumo do lote no canal de alertas: planejados, enviados, falhos, custo estimado

4.8.4 Resposta do assinante #

Assinante toca em "Ler e ouvir agora"
   │
   ├─► Canal ─── POST /api/webhooks/whatsapp ───► apps/web
   │                 ├─ valida assinatura HMAC do corpo cru
   │                 ├─ grava inbound_message
   │                 ├─ enfileira whatsapp.inbound
   │                 └─ responde 200 imediatamente
   │
   └─► worker: whatsapp.inbound
          ├─ localiza assinante: wa_id_hmac → phone_hmac → variantes de nono dígito
          ├─ PRIMEIRA operação sobre a mensagem, antes de qualquer outra:
          │     palavra de saída → opt_out_at, confirma uma única vez, para tudo.
          │     Precedência absoluta, válida em qualquer estado do assinante,
          │     inclusive em atendimento humano ou modo silencioso (Seção 19.5)
          ├─ atualiza service_window_expires_at = agora + 24 h
          ├─ classifica o restante:
          │     payload OPEN_DEVOTIONAL  → entrega o pacote do dia
          │     payload SNOOZE           → reagenda para 12:00 do mesmo dia
          │     palavra de retorno       → limpa opt_out_at, confirma
          │     texto livre              → responde com o menu de ajuda
          └─ toda entrega respeita o nível de acesso relido no instante do envio

4.9 Decisões de arquitetura e seus custos #

4.10 Canal oficial em vez de intermediário, e a camada que permite trocar #

Decisão: integrar diretamente à API oficial do canal de mensageria, sem provedor intermediário.

Motivos: custo por mensagem sem margem de terceiro; ausência de assinatura mensal fixa, relevante enquanto a base é pequena; acesso imediato a recursos novos, sem esperar o intermediário implementar; controle direto sobre o cadastro e a aprovação de templates; e um elo a menos na cadeia de entrega, o que reduz a superfície de falha do momento mais crítico do dia.

O que se perde: suporte humano em incidente, painéis prontos de análise, filas gerenciadas e ferramentas de atendimento. Como o produto é de entrega, não de atendimento, a perda é aceitável.

Gatilhos objetivos para migrar para um intermediário, decididos desde já: volume mensal acima de 500.000 mensagens; necessidade de mais de um número na mesma operação; ou dois incidentes de suspensão de conta em doze meses. Nenhum deles exige reescrever o motor de envio, por causa da abstração abaixo.

// packages/integrations/src/whatsapp/provider.ts
export interface WhatsAppProvider {
  sendTemplate(input: SendTemplateInput): Promise<SendResult>
  sendText(input: SendTextInput): Promise<SendResult>
  sendAudio(input: SendAudioInput): Promise<SendResult>
  uploadMedia(input: UploadMediaInput): Promise<{ mediaId: string; expiresAt: Date }>
  markAsRead(messageId: string): Promise<void>
  parseInboundWebhook(rawBody: string, signature: string): InboundEvent[]
}

export type SendResult =
  | { ok: true; providerMessageId: string; conversationCategory: string | null }
  | { ok: false; error: ProviderError }

/** Erro já traduzido para o vocabulário interno; o motor nunca vê código bruto. */
export interface ProviderError {
  kind:
    | 'OUTSIDE_SERVICE_WINDOW'
    | 'UNDELIVERABLE'
    | 'DELIVERY_THROTTLED'
    | 'TEMPLATE_PROBLEM'
    | 'RATE_LIMITED'
    | 'ACCOUNT_PROBLEM'
    | 'UNKNOWN'
  providerCode: string
  retryable: boolean
  retryAfterMs?: number
  message: string
}

O motor de envio (Seção 18) depende apenas desta interface. Trocar de provedor significa escrever uma segunda implementação e mudar uma linha de composição no início do worker. A tradução de códigos de erro do canal para ProviderError.kind fica dentro da implementação, e é o único lugar do sistema que conhece números de erro de terceiros. O mesmo padrão vale para voz (TtsProvider, Seção 16) e para pagamentos.

4.11 Limites de escala do desenho #

Dimensionamento de referência: 10.000 assinantes no primeiro ano, sendo 3.000 pagos; arquitetura sustentada até 50.000 sem mudança estrutural. Uma máquina com 4 vCPU e 8 GB de memória atende com folga.

Contas que sustentam a afirmação: 3.000 mensagens a 20 por segundo levam 2,5 minutos de chamadas ao canal; a janela de envio permitida é de 20 minutos, o que deixa margem de oito vezes para retries. No domingo, 10.000 mensagens levam cerca de 8,5 minutos. O áudio é gerado uma vez por devocional, não por assinante: 30 gerações por mês, independentemente do tamanho da base. O volume diário de registros de mensagem em 50.000 assinantes fica na casa de 150.000 linhas por dia, o que a partição mensal absorve.

O que não muda em nenhum desses cenários: a fonte única de verdade continua sendo o banco relacional; o áudio continua sendo gerado uma vez por devocional; e o envio continua idempotente por assinante e data.

4.12 Topologia de processos #

As migrações são aplicadas na inicialização do container da aplicação web, com bloqueio de advertência no banco para impedir execução concorrente. O worker aguarda o banco estar na versão esperada antes de consumir filas; se a versão divergir, ele registra erro e não consome, para evitar processar com schema antigo. Detalhes de deploy, imagens e volumes estão na Seção 25.

5. Convenções de Código e Padrões de Projeto #

5.1 Princípios #

1. Regra de negócio mora no domínio. Rota HTTP e job de fila são cascas finas.
2. Uma regra, um lugar. Nível de acesso, normalização de telefone, estados da assinatura e chaves de idempotência existem uma única vez, no domínio compartilhado.
3. Validação na borda, tipos por dentro. Toda entrada externa passa por Zod. Depois disso, o código confia nos tipos.
4. Erro é dado, não exceção genérica. Todo erro previsível tem código estável.
5. Explícito vence esperto. Sem metaprogramação, sem abstração antecipada, sem herança profunda.

5.2 Convenções de nomes #

Proibições explícitas: abreviações inventadas (subsc, dvtnl); prefixo húngaro; sufixo Manager, Helper ou Util em nome de módulo; arquivo utils.ts genérico — o nome descreve o que faz (format-currency.ts, sanitize-teaser.ts).

Duas regras de dinheiro que valem em todo o código, sem exceção: nunca use ponto flutuante para valor monetário, e nunca misture centavos com micros na mesma fórmula sem conversão explícita. Os divisores são fixos: centavos para reais divide por 100; micros para reais divide por 1_000_000. A conversão entre o decimal do provedor de pagamento e os centavos internos acontece em um único arquivo, packages/integrations/src/asaas/mapper.ts.

5.3 Imports e ordem #

Quatro grupos, separados por linha em branco, nesta ordem, com ordenação alfabética dentro de cada grupo. A regra é aplicada por lint com correção automática.

// 1. Node e bibliotecas externas
import { createHash } from 'node:crypto'
import { z } from 'zod'

// 2. Pacotes internos do monorepo
import { prisma } from '@pd/db'
import { AppError, resolveEntitlements } from '@pd/core'
import { whatsapp } from '@pd/integrations'

// 3. Módulos da própria aplicação, por alias absoluto
import { getSessionOrThrow } from '@/lib/session'
import { t } from '@/i18n/pt-BR'

// 4. Módulos irmãos, por caminho relativo curto
import { resendService } from './resend.service'
import type { ResendInput } from './resend.types'

Regras adicionais: aliases @pd/* para pacotes e @/* para o interior de cada aplicação, definidos em tsconfig.base.json; nada de ../../.. — a partir de dois níveis, use alias; import type obrigatório para importações que só carregam tipos; nenhuma exportação padrão, exceto onde o framework exige (páginas, layouts e route.ts); nenhum arquivo de reexportação em massa dentro de uma aplicação, porque quebra o descarte de código morto.

5.4 Estrutura interna de um módulo de domínio #

Um módulo de domínio agrupa arquivos por assunto, nunca por tipo técnico. Exemplo do módulo de assinatura em packages/core/src/subscription/:

subscription/
├── subscription.types.ts       # tipos e uniões discriminadas do domínio
├── subscription.schemas.ts     # Zod de entrada e saída deste assunto
├── subscription.errors.ts      # códigos de erro específicos do assunto
├── subscription.state.ts       # máquina de estados: transições permitidas e guardas
├── subscription.rules.ts       # funções puras de regra (ex.: cálculo de fim de ciclo)
├── index.ts                    # superfície pública do módulo, explícita
└── __tests__/
    ├── subscription.state.test.ts
    └── subscription.rules.test.ts

O index.ts exporta apenas o que outros módulos podem usar. Importar um arquivo interno de outro módulo é erro de lint. Isso mantém a superfície pequena e permite refatorar por dentro sem quebrar consumidores.

5.5 Camadas: route handler, service, repository #

Três camadas, com responsabilidades sem sobreposição:

Exemplo completo de uma operação real — reenvio manual do devocional do dia pedido pelo assinante no painel. O contrato normativo desta rota está na Seção 7; abaixo ela serve de referência de forma.

// apps/web/app/api/devotionals/[devotionalId]/resends/route.ts
import { NextRequest } from 'next/server'
import { AppError } from '@pd/core'
import { getSubscriberSession } from '@/lib/session'
import { fail, ok } from '@/lib/http'
import { resendTodayDevotional } from '@/server/devotional/resend.service'
import { ResendTodaySchema } from '@/server/devotional/resend.schemas'

export async function POST(req: NextRequest) {
  const requestId = req.headers.get('x-request-id') ?? undefined
  try {
    const session = await getSubscriberSession(req) // lança UNAUTHENTICATED
    const body = ResendTodaySchema.parse(await req.json().catch(() => ({})))
    const result = await resendTodayDevotional({
      subscriberId: session.subscriberId,
      channel: body.channel,
      requestId,
    })
    return ok(result, { requestId })
  } catch (error) {
    return fail(error, { requestId })
  }
}

// apps/web/src/server/devotional/resend.service.ts
import { AppError, resolveEntitlements, todayInSaoPaulo } from '@pd/core'
import { prisma, withTransaction } from '@pd/db'
import { enqueue } from '@/lib/queue'
import { subscriberRepo } from './subscriber.repo'
import { devotionalRepo } from './devotional.repo'
import { resendRepo } from './resend.repo'

export async function resendTodayDevotional(input: {
  subscriberId: string
  channel: 'whatsapp'
  requestId?: string
}) {
  const today = todayInSaoPaulo()

  return withTransaction(async (tx) => {
    // 1. Carrega o agregado com bloqueio, para tornar a contagem de reenvios segura.
    const subscriber = await subscriberRepo.findForUpdate(tx, input.subscriberId)
    if (!subscriber) throw new AppError('SUBSCRIBER_NOT_FOUND', 404)
    if (subscriber.optOutAt) throw new AppError('SUBSCRIBER_OPTED_OUT', 409)

    // 2. Regra de domínio: o que este assinante tem direito de fazer hoje.
    const entitlements = resolveEntitlements(subscriber, { now: today })

    // 3. Existe devocional atribuído a este assinante hoje?
    const devotional = await devotionalRepo.findSentToSubscriberOn(tx, subscriber.id, today)
    if (!devotional) {
      throw entitlements.tier === 'FREE'
        ? new AppError('NO_DEVOTIONAL_FOR_TODAY_ON_FREE_TIER', 409)
        : new AppError('NO_DEVOTIONAL_FOR_TODAY', 409)
    }

    // 4. Limite diário de reenvio, contado no fuso operacional.
    const used = await resendRepo.countForDay(tx, subscriber.id, today)
    if (used >= entitlements.resendLimitPerDay) {
      throw new AppError('RESEND_LIMIT_REACHED', 429, {
        details: [{ field: 'resend', issue: 'daily_limit', limit: entitlements.resendLimitPerDay }],
      })
    }

    // 5. Registro do consumo dentro da mesma transação: sem corrida, sem crédito extra.
    const attempt = await resendRepo.create(tx, {
      subscriberId: subscriber.id,
      devotionalId: devotional.id,
      day: today,
      sequence: used + 1,
    })

    // 6. Efeito colateral fora do banco só depois do commit.
    tx.afterCommit(() =>
      enqueue('send.dispatch', {
        subscriberId: subscriber.id,
        devotionalId: devotional.id,
        reason: 'MANUAL_RESEND',
        idempotencyKey: `resend:${subscriber.id}:${today}:${used + 1}`,
      }),
    )

    return {
      status: 'QUEUED' as const,
      remainingToday: entitlements.resendLimitPerDay - (used + 1),
      attemptId: attempt.id,
    }
  })
}

// apps/web/src/server/devotional/resend.repo.ts
import type { Tx } from '@pd/db'

export const resendRepo = {
  countForDay(tx: Tx, subscriberId: string, day: string) {
    return tx.deliveryAttempt.count({
      where: { subscriberId, deliveryDate: day, reason: 'MANUAL_RESEND' },
    })
  },

  create(tx: Tx, data: { subscriberId: string; devotionalId: string; day: string; sequence: number }) {
    return tx.deliveryAttempt.create({
      data: {
        subscriberId: data.subscriberId,
        devotionalId: data.devotionalId,
        deliveryDate: data.day,
        reason: 'MANUAL_RESEND',
        idempotencyKey: `resend:${data.subscriberId}:${data.day}:${data.sequence}`,
        status: 'QUEUED',
      },
    })
  },
}

Três pontos que o exemplo fixa como norma: a contagem e a gravação do consumo acontecem na mesma transação, com bloqueio de linha, o que elimina a corrida de dois cliques simultâneos; o enfileiramento só ocorre após o commit, o que impede job órfão apontando para um registro que não existe; e a regra de quanto vale o limite vem do domínio, não da rota.

5.6 Validação com Zod #

Os schemas de entrada e saída vivem em packages/core/src/schemas/ quando são compartilhados entre a aplicação web e o worker, e ao lado do módulo quando são locais. Web e worker importam o mesmo schema — nunca existem duas definições da mesma forma de dado.

// packages/core/src/schemas/subscriber.schemas.ts
import { z } from 'zod'
import { normalizePhoneBR } from '../phone'

/**
 * A validação de formato E.164 acontece **aqui**, na borda, antes de o valor ser cifrado.
 * A coluna que guarda o telefone é um envelope cifrado (Seção 6.3) e por isso não pode
 * carregar CHECK de formato: o banco não vê o valor. Zod é a única barreira de formato.
 */
export const PhoneBRSchema = z
  .string()
  .trim()
  .min(10, 'Telefone muito curto.')
  .transform((raw, ctx) => {
    const parsed = normalizePhoneBR(raw)
    if (!parsed.ok) {
      ctx.addIssue({ code: 'custom', message: 'Informe um celular brasileiro válido com DDD.' })
      return z.NEVER
    }
    return parsed.e164 // sempre +55DDNNNNNNNNN a partir daqui
  })

export const RegisterSubscriberSchema = z.object({
  name: z.string().trim().min(2).max(80),
  phone: PhoneBRSchema,
  email: z.email().optional(),
  consentAccepted: z.literal(true, { message: 'É necessário aceitar para continuar.' }),
  consentVersion: z.string().regex(/^v\d+$/),
})

export type RegisterSubscriberInput = z.infer<typeof RegisterSubscriberSchema>

Regras normativas de validação:

• Todo parse acontece na borda: route handler, consumidor de fila e comando da CLI. Nunca no meio de um service.
• Falha de validação vira VALIDATION_FAILED com details derivado das issues do Zod, uma entrada por campo, conforme o envelope de erro da Seção 7.
• Payload de job também é validado na entrada do worker. Um job antigo, enfileirado antes de um deploy, pode ter forma incompatível: nesse caso o job falha de forma explícita, em vez de corromper dados.
• Mensagens de validação são escritas em português do Brasil e seguras para exibir ao usuário final.
• z.coerce é proibido em entrada vinda da rede. Conversão explícita evita aceitar "0" onde se espera booleano.

5.7 Tratamento de erro no código #

Existe uma única classe de erro de negócio, e ela se chama AppError — em todo o sistema, em toda seção deste documento e em todo arquivo do repositório. O nome ApiError é proibido: não existe classe com esse nome, e uma regra de lint (no-restricted-syntax sobre NewExpression[callee.name='ApiError'] e sobre a declaração da classe) reprova o build se ele aparecer. A classe vive em packages/core/src/errors.ts e carrega o código estável, o status HTTP e os detalhes que o envelope de erro da Seção 7 exige. A mensagem em português vem do catálogo, não de texto solto no meio do código.

// packages/core/src/errors.ts
export interface ErrorDetail { field?: string; issue: string; [k: string]: unknown }

export class AppError extends Error {
  readonly code: string
  readonly status: number
  readonly details?: ErrorDetail[]
  readonly cause?: unknown
  /** true = falha esperada de negócio; registrada como warn, não como error. */
  readonly expected: boolean

  constructor(
    code: string,
    status = 400,
    options: { details?: ErrorDetail[]; cause?: unknown; expected?: boolean } = {},
  ) {
    super(ERROR_MESSAGES[code] ?? 'Não foi possível concluir a operação.')
    this.name = 'AppError'
    this.code = code
    this.status = status
    this.details = options.details
    this.cause = options.cause
    this.expected = options.expected ?? status < 500
  }
}

export function isAppError(e: unknown): e is AppError {
  return e instanceof AppError
}

O mapeamento para HTTP acontece em um único lugar por aplicação:

// apps/web/src/lib/http.ts
import { ZodError } from 'zod'
import { AppError, isAppError } from '@pd/core'
import { logger } from '@/lib/logger'

export function ok<T>(data: T, meta: { requestId?: string } = {}) {
  return Response.json(
    { data, meta: { requestId: meta.requestId, timestamp: new Date().toISOString() } },
    { status: 200, headers: meta.requestId ? { 'X-Request-Id': meta.requestId } : undefined },
  )
}

export function fail(error: unknown, meta: { requestId?: string } = {}) {
  const mapped = toAppError(error)
  const log = logger.child({ requestId: meta.requestId, code: mapped.code })
  if (mapped.expected) log.warn({ details: mapped.details }, 'request_failed_expected')
  else log.error({ err: mapped, cause: mapped.cause }, 'request_failed_unexpected')

  return Response.json(
    {
      error: { code: mapped.code, message: mapped.message, details: mapped.details },
      meta: { requestId: meta.requestId, timestamp: new Date().toISOString() },
    },
    { status: mapped.status },
  )
}

function toAppError(error: unknown): AppError {
  if (isAppError(error)) return error
  if (error instanceof ZodError) {
    return new AppError('VALIDATION_FAILED', 422, {
      details: error.issues.map((i) => ({ field: i.path.join('.') || undefined, issue: i.code })),
    })
  }
  return new AppError('INTERNAL_ERROR', 500, { cause: error, expected: false })
}

Regras: nenhum catch silencioso; nenhum throw de string ou objeto literal; erro de terceiro é traduzido na camada de integração, nunca vaza para a rota; detalhe interno (consulta SQL, corpo de resposta de terceiro, rastreamento de pilha) nunca entra no campo message, que é exibido ao usuário. O catálogo completo de códigos é da Seção 7.

5.8 Logging estruturado #

Um logger, criado uma vez por processo, sempre em JSON. Nunca console.log em código de produção — é erro de lint.

// packages/core/src/logger.ts
import pino from 'pino'

export function createLogger(service: 'web' | 'worker' | 'ops') {
  return pino({
    level: process.env.LOG_LEVEL ?? 'info',
    base: { service, env: process.env.APP_ENV, version: process.env.BUILD_SHA },
    timestamp: pino.stdTimeFunctions.isoTime,
    redact: {
      paths: [
        'req.headers.authorization', 'req.headers.cookie', 'req.headers["access_token"]',
        'req.headers["asaas-access-token"]', 'req.headers["x-hub-signature-256"]',
        '*.password', '*.passwordHash', '*.otp', '*.otpHash', '*.token', '*.accessToken',
        '*.creditCard', '*.creditCardNumber', '*.ccv', '*.cpfCnpj', '*.cpf',
        '*.phone', '*.phoneE164', '*.waId', '*.email', '*.apiKey', '*.secret',
        // URL assinada É credencial: quem tem a URL tem o arquivo.
        'url', 'mediaUrl', 'signedUrl', 'downloadUrl', 'audioUrl', 'videoUrl',
        'presignedUrl', 'invoiceUrl', '*.url', '*.mediaUrl', '*.signedUrl',
        '*.downloadUrl', '*.audioUrl', '*.videoUrl', '*.presignedUrl', '*.invoiceUrl',
      ],
      censor: '[REDACTED]',
    },
  })
}

Campos obrigatórios em todo registro de log, além dos automáticos: requestId nas rotas HTTP; jobId, jobName e attempt nos jobs; subscriberId quando houver assinante; devotionalId quando houver devocional; code quando houver erro. Mensagens de log são identificadores estáveis em inglês, em snake_case (daily_batch_planned, whatsapp_send_failed), porque são consultadas por filtro — a prosa em português fica na interface, não no log.

Proibições de conteúdo: telefone completo, número de documento, endereço de e-mail, código de acesso, token, corpo de mensagem enviada ao assinante, URL assinada de armazenamento ou de mídia da plataforma de mensagens e qualquer credencial. Para correlacionar sem expor, registre o identificador interno do assinante e, quando for inevitável identificar o telefone em investigação, apenas os quatro últimos dígitos, no campo phoneLast4. Mídia é referida por mediaKey — o caminho no bucket, sem host e sem assinatura — ou pelo identificador de mídia da plataforma, nunca pela URL completa.

5.9 Padrão de teste #

Convenção de nomes de caso: descreve o sujeito > deve <comportamento esperado> quando <condição>. Exemplo: resolveEntitlements > deve limitar o acervo a 7 dias quando o nível é FREE.

Factories ficam em packages/core/src/testing/factories/ e produzem objetos válidos por padrão, com sobrescrita parcial: makeSubscriber({ tier: 'PAID' }). Fixtures de payload de terceiros ficam em __fixtures__/ como JSON real capturado, e não inventado à mão. Toda suíte de integração roda dentro de uma transação revertida ao final, exceto quando o teste verifica commit; nesse caso, a base é truncada por lista explícita de tabelas.

Proibições: teste que depende de horário real — o instante é sempre injetado; teste que depende da ordem de execução; e chamada de rede a serviço externo em qualquer suíte, sem exceção. A estratégia completa, com metas de cobertura, é da Seção 24.

5.10 Lint e formatação #

// eslint.config.js (raiz do monorepo, formato flat)
import js from '@eslint/js'
import ts from 'typescript-eslint'
import importPlugin from 'eslint-plugin-import'
import a11y from 'eslint-plugin-jsx-a11y'

export default ts.config(
  js.configs.recommended,
  ...ts.configs.strictTypeChecked,
  {
    plugins: { import: importPlugin, 'jsx-a11y': a11y },
    languageOptions: { parserOptions: { projectService: true } },
    rules: {
      'no-console': 'error',
      'no-restricted-syntax': [
        'error',
        { selector: "NewExpression[callee.name='Date'][arguments.length=0]", message: 'Injete o instante; não leia o relógio dentro do domínio.' },
      ],
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-floating-promises': 'error',
      '@typescript-eslint/consistent-type-imports': 'error',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'import/order': ['error', {
        groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
        pathGroups: [{ pattern: '@pd/**', group: 'internal' }, { pattern: '@/**', group: 'internal' }],
        'newlines-between': 'always',
        alphabetize: { order: 'asc', caseInsensitive: true },
      }],
      'import/no-default-export': 'error',
      'jsx-a11y/alt-text': 'error',
      'jsx-a11y/label-has-associated-control': 'error',
    },
  },
  {
    // O framework de interface exige exportação padrão nestes arquivos.
    files: ['apps/web/app/**/{page,layout,route,error,loading,not-found}.tsx', 'apps/web/app/**/route.ts'],
    rules: { 'import/no-default-export': 'off' },
  },
  {
    // O domínio é puro: não conhece banco, rede nem ambiente.
    files: ['packages/core/**'],
    rules: {
      'no-restricted-imports': ['error', { patterns: ['@pd/db', '@pd/integrations', 'node:fs', 'node:net'] }],
    },
  },
)

// .prettierrc.json
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "arrowParens": "always",
  "plugins": ["prettier-plugin-tailwindcss"]
}

A verificação pnpm lint, pnpm typecheck e pnpm format:check roda em hook de pré-commit sobre os arquivos alterados e novamente na integração contínua sobre o repositório inteiro. Aviso de lint não existe: toda regra é erro ou não está configurada. Desativação pontual exige // eslint-disable-next-line <regra> -- motivo com o motivo escrito; comentário de desativação sem justificativa é reprovado na revisão.

5.11 Commits e branches #

Commits seguem Conventional Commits, com o assunto em português, no imperativo, sem ponto final e com no máximo 72 caracteres:

feat(delivery): pular template quando a janela de 24h estiver aberta
fix(billing): revogar acesso na mesma transação do evento de atraso
refactor(core): extrair cálculo de fim de ciclo para subscription.rules
test(phone): cobrir variantes de nono dígito em números de celular
chore(deps): atualizar dependências de desenvolvimento
docs(readme): registrar decisões configuráveis aplicadas

Tipos aceitos: feat, fix, refactor, perf, test, docs, build, ci, chore, revert. Escopos aceitos, alinhados aos módulos: web, worker, ops, db, core, integrations, auth, billing, delivery, content, media, metrics, infra. Mudança incompatível usa ! após o escopo e um rodapé BREAKING CHANGE:.

Branches: feat/, fix/, chore/, refactor/ seguidos de descrição curta em kebab-case. A branch main é protegida, sempre implantável, e recebe apenas merge com fast-forward após revisão e integração contínua verde. Rebase antes do merge; merge com histórico de merge comercial não é aceito. Uma branch por unidade de trabalho, vida útil máxima de três dias.

5.12 Comentários, TODOs e código morto #

• Comentário explica por quê, nunca o quê. Se o código precisa de comentário para ser entendido, o problema é o nome da função.
• TODO e FIXME são proibidos no código versionado. Trabalho pendente vira tarefa registrada fora do código. A regra é verificada na integração contínua: a presença de TODO, FIXME ou XXX em arquivo versionado reprova o build.
• Código morto é removido, não comentado. O histórico de versão é o arquivo morto.
• Nada de código "preparado para o futuro": parâmetro sem uso, flag que nunca liga, abstração com uma única implementação prevista. Cada um deles é removido na revisão.
• Comentário obrigatório em três situações: contorno de limitação de terceiro (com o código de erro que o motiva), decisão contraintuitiva de desempenho e trecho que reproduz uma regra legal ou de plataforma.
• Documentação de módulo, quando necessária, é um bloco no topo do arquivo index.ts, descrevendo a superfície pública em três linhas.

5.13 Acessibilidade nos componentes #

O alvo é WCAG 2.2 nível AA em todas as superfícies, verificado conforme a Seção 24. Regras que valem no momento de escrever o componente:

• HTML semântico primeiro: button para ação, a para navegação, label associado a todo campo. div com onClick é erro de lint.
• Todo campo de formulário tem rótulo visível; texto de ajuda ligado por aria-describedby; erro anunciado com role="alert" e vinculado ao campo por aria-errormessage.
• Foco sempre visível, com anel de contraste mínimo de 3:1. Remover o indicador de foco é proibido.
• Ordem de tabulação segue a ordem visual. Diálogos prendem o foco, devolvem o foco ao elemento de origem ao fechar e respondem à tecla Escape.
• Estados de carregamento e conclusão são anunciados por região viva (aria-live="polite"). Isso vale para o player de áudio e para o botão de reenvio.
• Contraste mínimo de 4,5:1 para texto normal e 3:1 para texto grande e componentes de interface. A paleta padrão de 1.5 já atende.
• Alvo de toque mínimo de 44 por 44 pixels em telas pequenas.
• Nenhuma informação transmitida só por cor: estado de assinatura tem rótulo em texto, além da cor.
• Animação respeita prefers-reduced-motion; transições decorativas são suprimidas.
• Áudio do devocional é acompanhado do texto completo na mesma página, o que satisfaz a alternativa textual para conteúdo sonoro.
• Idioma declarado no documento: <html lang="pt-BR">.

5.14 Textos de interface #

Todo texto exibido ao usuário vive em um único arquivo por aplicação, nunca solto no JSX. Não há biblioteca de internacionalização, porque não há segundo idioma — e adicionar uma agora seria complexidade sem uso.

// apps/web/src/i18n/pt-BR.ts
export const messages = {
  brand: { name: 'Palavra Diária' },
  common: {
    save: 'Salvar',
    cancel: 'Cancelar',
    loading: 'Carregando…',
    genericError: 'Não foi possível concluir. Tente novamente em instantes.',
  },
  subscriber: {
    resend: {
      button: 'Reenviar devocional de hoje',
      queued: 'Enviamos de novo. Deve chegar em alguns segundos.',
      limitReached: 'Você já usou seus reenvios de hoje. Amanhã libera de novo.',
      freeTierNoDevotional: 'No plano gratuito o devocional chega aos domingos.',
    },
    archive: {
      lockedTitle: 'Disponível no plano pago',
      lockedBody: 'Assine para ler todo o acervo e receber o áudio todos os dias.',
    },
  },
} as const

type Leaves<T> = T extends string ? '' : { [K in keyof T & string]: `${K}${Leaves<T[K]> extends '' ? '' : `.${Leaves<T[K]>}`}` }[keyof T & string]
export type MessageKey = Leaves<typeof messages>

export function t(key: MessageKey): string {
  return key.split('.').reduce<unknown>((acc, part) => (acc as Record<string, unknown>)[part], messages) as string
}

Regras: chave em inglês, valor em português do Brasil; agrupamento por superfície, não por tela; texto literal em JSX é erro de revisão; mensagens de erro exibidas ao usuário vêm do catálogo de erros (Seção 7) e não deste arquivo, para que a mesma falha diga a mesma coisa na interface e na API; valores dinâmicos usam função em vez de concatenação (t('x.y') para texto fixo, funções nomeadas para texto com variável), preservando a concordância em português.

5.15 Lista de verificação antes de abrir uma revisão #

1. pnpm lint, pnpm typecheck, pnpm test e pnpm format:check passam localmente.
2. Nenhum console.log, TODO, FIXME ou código comentado.
3. Toda entrada externa nova tem schema Zod e todo erro novo tem código no catálogo.
4. Nenhuma regra de negócio nova dentro de route handler ou de componente.
5. Nenhum dado pessoal novo em log; campos sensíveis adicionados à lista de redação.
6. Migração de banco acompanhada de teste de integração e reversível.
7. Texto de interface no arquivo único, não no JSX.
8. Componente novo navegável por teclado e com rótulos associados.
9. Commit no formato convencional, com escopo válido.
10. Nada fora do escopo definido em 2.7 foi introduzido.

6. Modelo de Dados e Schema do Banco #

Esta seção é a fonte única da verdade do modelo de dados. Nenhuma outra seção define tabelas, colunas, índices ou enums. Onde outra seção precisar falar de persistência, ela referencia a subseção correspondente aqui.

O banco é PostgreSQL na linha de versão declarada na Seção 4. O ORM e o mecanismo de migrations são Prisma, também na linha declarada na Seção 4.

6.1 Princípios do modelo e convenções aplicadas #

6.1.1 Regras estruturais #

6.1.2 Por que ULID e não UUID #

ULID é ordenável por tempo de criação. Isso dá três ganhos diretos neste produto:

1. Índices B-tree com inserção quase sequencial. As tabelas de maior volume (message_logs, delivery_attempts, inbound_messages) recebem escrita concentrada entre 05:40 e 06:20. Com UUIDv4 a inserção espalha por todo o índice e infla o WAL.
2. Paginação por cursor barata. A ordenação padrão ORDER BY id DESC já é cronológica, então o cursor da Seção 7.8 pode ser o próprio id na maioria das listas.
3. Depuração. O ULID 01K3F8QZ7M0000000000000000 carrega o instante de criação em seus 10 primeiros caracteres, o que acelera correlação com logs.

Geração exclusivamente na aplicação, via biblioteca ulid (linha 3.x). O banco não tem default para id — a ausência de default é intencional e força o caminho único de geração. Nenhuma migration ou seed pode inserir id fora desse formato.

Validação de formato garantida por CHECK global em todas as tabelas com id:

CONSTRAINT chk_<tabela>_id_ulid CHECK (id ~ '^[0-9A-HJKMNP-TV-Z]{26}$')

O alfabeto é o Crockford Base32 (sem I, L, O, U), sempre em maiúsculas.

6.1.3 Prefixos públicos de identificador #

O id no banco é o ULID cru. Na API pública ele é exposto com prefixo por entidade, convertido na borda de serialização e nunca persistido com prefixo.

Um identificador recebido pela API com prefixo errado devolve VALIDATION_ERROR (catálogo na Seção 7.11), nunca NOT_FOUND — o prefixo é sintaxe, não existência.

6.1.4 Concorrência e versionamento otimista #

Três tabelas têm edição concorrente real (dois administradores no mesmo recurso) e por isso carregam coluna version integer NOT NULL DEFAULT 1:

• devotionals — dois editores no mesmo devocional;
• settings — dois administradores ajustando runtime;
• whatsapp_templates — submissão concorrente à Meta.

O UPDATE sempre inclui WHERE version = :expectedVersion e incrementa a coluna. Zero linhas afetadas devolve OPTIMISTIC_LOCK_FAILED (Seção 7.11). Exemplo:

UPDATE devotionals
   SET title = $2, reflection_md = $3, version = version + 1, updated_at = now()
 WHERE id = $1 AND version = $4 AND deleted_at IS NULL;
-- 0 linhas => OPTIMISTIC_LOCK_FAILED

As demais tabelas não usam versionamento otimista: ou são append-only, ou têm dono único (o worker), ou a última escrita legitimamente vence.

6.1.5 Extensões Postgres exigidas #

CREATE EXTENSION IF NOT EXISTS citext;      -- e-mails case-insensitive
CREATE EXTENSION IF NOT EXISTS pgcrypto;    -- digest() para hashes em migrations e seeds
CREATE EXTENSION IF NOT EXISTS pg_trgm;     -- busca por trecho em títulos de devocionais
CREATE EXTENSION IF NOT EXISTS btree_gin;   -- índices compostos com jsonb em auditoria
CREATE EXTENSION IF NOT EXISTS unaccent;    -- normalização de busca editorial em PT-BR

unaccent é usado apenas na busca administrativa de devocionais. Palavras-chave de opt-out chegam pelo WhatsApp e são normalizadas em TypeScript (String.normalize('NFD')), não no banco, porque o worker precisa decidir sem ida ao banco.

6.1.6 Catálogo de enums #

Todos os enums são tipos nativos do Postgres, criados e versionados pelo Prisma. Adicionar valor a enum é operação de migration própria (ALTER TYPE ... ADD VALUE), nunca misturada com outras alterações, porque em Postgres o novo valor não pode ser usado na mesma transação em que foi criado.

São 35 tipos enum. Quatro deles merecem explicação, porque a escolha de valores é consequência direta de decisões tomadas em outras seções:

1. SubscriberStatus tem sete valores e DELETED não está entre eles. Conta excluída não é um estado do enum: é subscribers.deleted_at preenchido. Misturar exclusão com estado operacional criaria um oitavo valor que nenhuma transição consegue deixar, e quebraria o índice parcial de elegibilidade, que já filtra por deleted_at IS NULL. As transições completas estão na Seção 11.8.1; a garantia física está em 6.3.3. BLOCKED tem entrada (bloqueio administrativo ou erro permanente da Meta) e saída (desbloqueio administrativo ou mensagem recebida do assinante) — não é estado morto.
2. JobRunStatus tem DEAD. Não existe fila de dead-letter no sistema. Um job que esgota as tentativas fica no estado failed da própria fila do BullMQ e grava uma linha em job_runs com status = 'DEAD'. job_runs é a dead-letter do sistema (Seção 18.8). Nenhuma seção pode introduzir uma fila com sufixo .dlq.
3. DeliveryAttemptStatus tem dois motivos de pulo explícitos. SKIPPED_OPTED_OUT e SKIPPED_INELIGIBLE existem porque o tier e o consentimento são revalidados no instante do disparo, e não no planejamento (Seção 18.5): o item precisa registrar por que não saiu, sem depender de texto livre. SKIPPED genérico permanece para os pulos decididos já no planejamento.
4. SessionScope existe para que a impersonação seja estruturalmente somente leitura. Uma sessão IMPERSONATION_READONLY é recusada em qualquer método não seguro antes de chegar ao handler (Seção 8.13.3), e uma sessão RESTRICTED é a que a reverificação por dormência emite (Seção 8.15.1.1). O escopo mora na linha da sessão, no banco, e não apenas no token — assim ele não pode ser perdido em uma renovação.

6.1.7 Lista fechada de tabelas #

O modelo tem exatamente 28 tabelas. A lista é fechada: nenhuma outra seção pode introduzir tabela nova. Necessidade de persistência não coberta usa settings (chave/valor tipado, Seção 6.23) e declara isso explicitamente.

A tabela 28, unsubscribe_tokens, é a persistência do link público de descadastro (POST /api/public/unsubscribe). Ela é definida por completo em 6.7.4 — colunas, tipos, índices, chave estrangeira com ON DELETE e retenção — e nenhuma outra seção redefine qualquer parte dela: as Seções 20 e 22 apenas a referenciam.

Duas tabelas concentram mais de 80% do volume: message_logs e delivery_attempts. O tratamento específico delas está em 6.33 (particionamento e retenção) e 6.34 (manutenção).

6.1.8 Invariante de dado pessoal #

Nenhuma tabela deste modelo armazena telefone, wa_id, e-mail ou CPF em texto claro. Onde a busca por igualdade é necessária, ela é feita pela coluna _hmac correspondente — um índice cego, HMAC-SHA-256 determinístico do valor normalizado, com chave própria e distinta da chave de cifra. As colunas cifradas e as colunas de índice cego são declaradas aqui, na Seção 6, e existem desde a primeira migration: não são endurecimento posterior, são schema. A Seção 22 descreve o algoritmo do envelope, a gestão da chave e o procedimento de rotação, e referencia esta seção para saber quais colunas existem.

As quatro duplas são:

Três regras derivam disso e valem em todo o documento:

1. Nenhum CHECK de banco valida o conteúdo de uma coluna cifrada. O banco só enxerga o envelope, então validar formato de telefone, de e-mail ou de CPF em SQL é impossível. A validação de formato é da camada de aplicação, por Zod, na borda, antes de cifrar (Seção 22.2.1). O único CHECK admissível sobre coluna cifrada é o do formato do envelope (~ '^v[0-9]+:'), que não revela nada.
2. Nenhuma consulta compara coluna cifrada por igualdade. A cifra é aleatorizada por nonce: dois envelopes do mesmo telefone são bytes diferentes. Toda busca por telefone, wa_id, e-mail ou CPF usa a coluna _hmac (6.35.3).
3. Um teste de schema percorre information_schema.columns e falha se encontrar coluna chamada phone_e164, wa_id, email ou cpf cujo tipo não seja text com o CHECK de envelope, ou cuja coluna _hmac correspondente esteja ausente. O teste roda no pipeline, contra o banco recém-migrado.

6.2 Diagrama ER #

                        ┌──────────────────────┐
                        │      plans           │
                        │  code (uniq)         │
                        │  interval            │
                        │  amount_cents        │
                        └───────────┬──────────┘
                                    │ 1
                                    │
                                    │ N
┌──────────────────┐ 1     1 ┌──────┴───────────────┐ 1    N ┌────────────────────────┐
│ subscriber_      ├─────────┤    subscriptions     ├────────┤  subscription_events   │
│   profiles       │         │  status              │        │  type / from / to      │
│  cpf (cifrado)   │         │  billing_type        │        │  cancel_reason         │
│  cpf_hmac (idx)  │         │  current_period_end  │        └────────────────────────┘
└──────────────────┘         │  pending_plan_id     │
          │ 1                └──────┬───────────────┘
          │                         │ 1
          │ 1                       │
┌─────────┴────────────┐            │ N        ┌──────────────────────┐
│     subscribers      │     ┌──────┴──────────┤   payment_events     │
│  phone_e164 (cifr.)  │     │   payments      │   asaas_event_id     │
│  phone_hmac (uniq)   │ 1  N│  asaas_payment  │   (uniq)             │
│  wa_id (cifrado)     ├─────┤   _id (uniq)    └──────────────────────┘
│  wa_id_hmac (uq p.)  │     └─────────────────┘
│  email (cifrado)     │
│  email_hmac (uq p.)  │
│  tier / status       │
│  opt_in_confirmed_at │
│  paused_until        │
│  service_window_     │
│    expires_at        │ 1   N ┌──────────────────────┐
│  deleted_at          ├───────┤   consent_events     │  append-only
└──┬───┬───┬───┬───┬───┘       └──────────────────────┘
   │   │   │   │   │
   │   │   │   │   │ N  ┌────────────────┐
   │   │   │   │   └────┤   sessions     │──┐ self-FK (rotação)
   │   │   │   │        │  refresh_hash  │◄─┘
   │   │   │   │        └────────────────┘
   │   │   │   │ N  ┌────────────────┐
   │   │   │   └────┤   otp_codes    │
   │   │   │        └────────────────┘
   │   │   │ N  ┌──────────────────────┐
   │   │   └────┤  inbound_messages    │  wamid (uniq)
   │   │        └──────────────────────┘
   │   │ N  ┌──────────────────────────┐ N   1 ┌───────────────────────┐
   │   └────┤   delivery_attempts      ├───────┤    send_batches       │
   │        │  idempotency_key (uniq)  │       │ idempotency_key(uniq) │
   │        │  step / status           │       │ devotional_date       │
   │        └────────────┬─────────────┘       └───────────┬───────────┘
   │                     │ N                               │ N
   │ N                   │                                 │
┌──┴──────────────────┐  │ 1                               │ 1
│    message_logs     │  │                    ┌────────────┴───────────┐
│  PARTITION BY RANGE │  │                    │      devotionals       │
│    (created_at)     │  └────────────────────┤  scheduled_for (uniq)  │
│  wamid              │      N              1 │  status / teaser       │
│  status/error_code  │                       │  version               │
└─────────────────────┘                       └──┬──────────┬──────────┘
                                                 │ 1        │ 1
                                                 │ N        │ N
                                  ┌──────────────┴───┐  ┌───┴─────────────────────┐
                                  │  audio_assets    │  │  devotional_revisions   │
                                  │  provider/format │  │  revision_number        │
                                  └────────┬─────────┘  └─────────────────────────┘
                                           │ 1
                                           │ N
                                  ┌────────┴─────────┐
                                  │  media_uploads   │
                                  │ whatsapp_media_id│
                                  │ expires_at (30d) │
                                  └──────────────────┘

┌──────────────────┐  1   N ┌────────────────────┐
│   admin_users    ├────────┤  admin_audit_log   │
│  email (uniq)    │        │  action/entity     │
│  totp_secret_enc │        └────────────────────┘
└────────┬─────────┘
         │ 1
         │ N
┌────────┴──────────────┐
│ admin_trusted_devices │
│  token_hash (uniq)    │
│  expires_at (30d)     │
└───────────────────────┘

┌──────────────────────┐  1   N ┌─────────────────────────┐
│     subscribers      ├────────┤   unsubscribe_tokens    │  ON DELETE CASCADE
│   (a mesma acima)    │        │  token_hash (uniq)      │
└──────────────────────┘        │  expires_at / used_at   │
                                └─────────────────────────┘

TABELAS SEM RELACIONAMENTO OBRIGATÓRIO (configuração, mensageria e operação):
┌──────────────┐ ┌────────────────┐ ┌──────────────────────────┐ ┌────────────────────┐
│  settings    │ │ feature_flags  │ │      daily_metrics       │ │ whatsapp_templates │
│  key (PK)    │ │  key (PK)      │ │ (metric_date, metric_key,│ │ (name, language)   │
│ grupo.chave  │ │  snake_case    │ │  dimension) uq — formato │ │       uq           │
│              │ │                │ │  longo                   │ │                    │
└──────────────┘ └────────────────┘ └──────────────────────────┘ └────────────────────┘
┌────────────────────────┐ ┌──────────────────────────────┐
│  webhook_deliveries    │ │  job_runs                    │
│  direction / source    │ │  job_name / queue            │
│  processing_result     │ │  status DEAD = dead-letter   │
└────────────────────────┘ └──────────────────────────────┘

LEGENDA: 1──N = um para muitos.  (uniq) = índice único.  (uniq part.) / (uq p.) = índice
único parcial.  (cifr.) / (cifrado) = envelope AES-256-GCM, nunca indexado.  (idx) = índice
não único.

6.3 Tabela subscribers #

Registro central do assinante: identidade por telefone, tier vigente, estado de opt-in e estado da janela de atendimento do WhatsApp.

6.3.1 Índices #

6.3.2 Chaves estrangeiras #

6.3.3 Constraints CHECK #

ALTER TABLE subscribers
  ADD CONSTRAINT chk_subscribers_phone_envelope
      CHECK (phone_e164 ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_subscribers_phone_hmac
      CHECK (phone_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_subscribers_wa_id_envelope
      CHECK (wa_id IS NULL OR wa_id ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_subscribers_wa_id_hmac
      CHECK (wa_id_hmac IS NULL OR wa_id_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_subscribers_wa_id_pair
      CHECK ((wa_id IS NULL) = (wa_id_hmac IS NULL)),
  ADD CONSTRAINT chk_subscribers_email_envelope
      CHECK (email IS NULL OR email ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_subscribers_email_hmac
      CHECK (email_hmac IS NULL OR email_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_subscribers_email_pair
      CHECK ((email IS NULL) = (email_hmac IS NULL)),
  ADD CONSTRAINT chk_subscribers_optout_after_optin
      CHECK (opt_out_at IS NULL OR opt_in_confirmed_at IS NULL
             OR opt_out_at >= opt_in_confirmed_at),
  ADD CONSTRAINT chk_subscribers_window_misses
      CHECK (consecutive_window_misses BETWEEN 0 AND 365),
  ADD CONSTRAINT chk_subscribers_undelivered_days
      CHECK (undelivered_days BETWEEN 0 AND 365),
  ADD CONSTRAINT chk_subscribers_undeliverable_count
      CHECK (undeliverable_count BETWEEN 0 AND 365),
  ADD CONSTRAINT chk_subscribers_unrecognized_replies
      CHECK (unrecognized_replies_in_window BETWEEN 0 AND 100),
  ADD CONSTRAINT chk_subscribers_status_verification
      CHECK (status <> 'PENDING_VERIFICATION' OR phone_verified_at IS NULL),
  ADD CONSTRAINT chk_subscribers_status_verified_pending
      CHECK (status <> 'VERIFIED_PENDING_OPTIN'
             OR (phone_verified_at IS NOT NULL AND opt_in_confirmed_at IS NULL)),
  ADD CONSTRAINT chk_subscribers_status_active_needs_optin
      CHECK (status NOT IN ('ACTIVE_FREE','ACTIVE_PAID','PAUSED')
             OR opt_in_confirmed_at IS NOT NULL),
  ADD CONSTRAINT chk_subscribers_status_tier_matches
      CHECK ((status <> 'ACTIVE_PAID' OR tier = 'PAID')
         AND (status <> 'ACTIVE_FREE' OR tier = 'FREE')),
  ADD CONSTRAINT chk_subscribers_status_paused
      CHECK (status <> 'PAUSED' OR paused_until IS NOT NULL),
  ADD CONSTRAINT chk_subscribers_status_optout
      CHECK ((status = 'OPTED_OUT') = (opt_out_at IS NOT NULL
                                       AND blocked_at IS NULL
                                       AND deleted_at IS NULL)),
  ADD CONSTRAINT chk_subscribers_status_blocked
      CHECK ((status = 'BLOCKED') = (blocked_at IS NOT NULL AND deleted_at IS NULL)),
  ADD CONSTRAINT chk_subscribers_blocked_pair
      CHECK ((blocked_at IS NULL) = (blocked_reason IS NULL)),
  ADD CONSTRAINT chk_subscribers_anonymized
      CHECK (anonymized_at IS NULL OR deleted_at IS NOT NULL),
  ADD CONSTRAINT chk_subscribers_full_anonymized_order
      CHECK (fully_anonymized_at IS NULL
             OR (anonymized_at IS NOT NULL AND fully_anonymized_at >= anonymized_at));

Três observações que evitam erro de implementação:

1. Não existe CHECK de formato E.164 nesta tabela, e não pode existir. phone_e164 guarda um envelope cifrado; um CHECK com a expressão '^\+[1-9][0-9]{7,14}$' sobre ele faria todo INSERT de assinante falhar. A validação do formato é do Zod, na borda, antes de cifrar (6.1.8, regra 1). O que o banco valida aqui é apenas o formato do envelope e o formato hexadecimal do índice cego.
2. wa_id não carrega o +: a Meta devolve o número sem sinal. Comparar telefone com wa_id exige remover o + antes de calcular o HMAC. Isso é responsabilidade de packages/core/src/phone.ts, nunca de SQL ad hoc, e a normalização canônica está na Seção 11.4.
3. DELETED não aparece em nenhum destes CHECKs porque não é um valor de SubscriberStatus. Exclusão é deleted_at IS NOT NULL, e os dois CHECKs de OPTED_OUT e BLOCKED já exigem deleted_at IS NULL para valer, o que mantém a linha excluída fora das duas equivalências sem precisar de um estado próprio.

6.3.4 A coluna status é derivada, e por que ela existe assim mesmo #

status é redundante em relação a phone_verified_at, opt_in_confirmed_at, paused_until, opt_out_at, blocked_at e tier. A redundância é deliberada: a consulta de planejamento diário roda uma vez por dia sobre toda a base e precisa de um índice parcial estreito. Índice parcial sobre seis colunas nulas produz plano pior do que sobre um enum.

O enum tem sete valores. Regra de consistência, aplicada em uma única função applySubscriberStatus() em packages/core e garantida pelos CHECKs de 6.3.3:

A precedência é fixa nessa ordem. Nenhum caminho de escrita pode gravar status direto.

Exclusão não é status. Conta excluída tem deleted_at preenchido e conserva o último status operacional que tinha. Toda consulta de produto filtra por deleted_at IS NULL, e os índices parciais de 6.3.1 já embutem esse filtro. O motivo é prático: se DELETED fosse um valor do enum, seria um estado sem transição de saída, e as duas equivalências de OPTED_OUT e BLOCKED deixariam de valer no instante da exclusão, obrigando a reescrever o status de uma linha que ninguém mais deveria tocar.

BLOCKED tem entrada e saída. Entra por bloqueio administrativo explícito ou por erro permanente da Meta (código 131026 em três dias consecutivos, ou bloqueio pelo assinante detectado por webhook), gravando blocked_at e blocked_reason; os envios cessam e a cobrança não é alterada. Sai por desbloqueio administrativo ou por qualquer mensagem recebida do assinante, que zera blocked_at e blocked_reason e devolve o assinante ao status resolvido pela tabela acima. As transições completas, com gatilho e efeito, estão na Seção 11.8.1.

6.3.5 A denormalização current_subscription_id #

Sem essa coluna, saber o tier vigente de um assinante exige uma junção com subscriptions filtrando por status e período. No pico de 05:40, com 10.000 linhas, isso é aceitável; com 50.000, não. A coluna guarda a assinatura vigente e é atualizada na mesma transação que muda subscriptions.status.

tier continua sendo a fonte de verdade dos entitlements. current_subscription_id é navegação, não autorização. Um job de reconciliação diário (Seção 6.35.7 traz a consulta) detecta divergência entre subscribers.tier e o estado real da assinatura e emite alerta.

6.4 Tabela subscriber_profiles #

Dados cadastrais e sensíveis do assinante, separados da tabela principal para que o caminho quente de envio nunca carregue CPF, IP ou user-agent.

6.4.1 Índices #

A unicidade de CPF não é imposta, e isso é uma decisão, não um esquecimento. Duas razões concretas, ambas com caso real no Brasil:

1. Um titular que pediu eliminação mantém cpf e cpf_hmac por até 5 anos, por obrigação fiscal (Seção 22.9, estágio 1). Um índice único o impediria de voltar a assinar: o INSERT colidiria com a linha anonimizada dele mesmo, e o checkout devolveria um erro de banco que nenhum operador de suporte consegue interpretar.
2. É corriqueiro que uma pessoa contrate para um familiar usando o próprio CPF — mãe que assina para si e depois para a filha. Com índice único, a segunda assinatura falha.

O mesmo cpf_hmac em mais de duas contas ativas incrementa a pontuação de risco da Seção 22.6.3 em 25 pontos e aparece na tela de assinantes como sinal para o operador. Detectar e sinalizar é o comportamento desejado; bloquear no banco não é.

6.4.2 Chaves estrangeiras #

CASCADE é correto aqui e só aqui no grupo de identidade: quando um assinante é apagado de fato (hard delete, que só ocorre no expurgo pós-anonimização), o perfil não tem razão de existir. Soft delete não dispara cascade.

6.4.3 Constraints CHECK #

ALTER TABLE subscriber_profiles
  ADD CONSTRAINT chk_profiles_state CHECK (state IS NULL OR state ~ '^[A-Z]{2}$'),
  ADD CONSTRAINT chk_profiles_cpf_last4 CHECK (cpf_last4 IS NULL OR cpf_last4 ~ '^[0-9]{4}$'),
  ADD CONSTRAINT chk_profiles_cpf_envelope CHECK (cpf IS NULL OR cpf ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_profiles_cpf_hmac CHECK (cpf_hmac IS NULL OR cpf_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_profiles_cpf_pair
      CHECK ((cpf IS NULL) = (cpf_hmac IS NULL)),
  ADD CONSTRAINT chk_profiles_birth_date
      CHECK (birth_date IS NULL OR birth_date BETWEEN DATE '1900-01-01' AND CURRENT_DATE);

Como em subscribers, nenhum CHECK valida o conteúdo do CPF: a coluna guarda um envelope. O dígito verificador é conferido por Zod na borda, antes de cifrar, e o erro correspondente é TAX_ID_INVALID (Seção 7.11). O CHECK de envelope e o de formato hexadecimal do índice cego são os únicos que o banco consegue aplicar sem enxergar o valor.

6.5 Tabela consent_events #

Trilha imutável de consentimento. É a prova documental exigida pela LGPD e a defesa em caso de reclamação de spam no WhatsApp.

Sem updated_at. Sem deleted_at. A tabela é append-only, com garantia no banco (ver 6.36.3).

6.5.1 Índices #

6.5.2 Chaves estrangeiras #

RESTRICT é intencional e é a razão de a tabela sobreviver ao expurgo do titular: o processo de eliminação por LGPD anonimiza o assinante (zera telefone, e-mail e nome) mas não apaga a linha, exatamente para preservar o vínculo com o consentimento durante os 5 anos de retenção. Um DELETE acidental em subscribers falha em vez de destruir prova.

6.5.3 Constraints CHECK #

ALTER TABLE consent_events
  ADD CONSTRAINT chk_consent_hash CHECK (consent_text_hash ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_consent_policy_version CHECK (policy_version ~ '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'),
  ADD CONSTRAINT chk_consent_web_evidence
      CHECK (channel <> 'WEB' OR ip IS NOT NULL),
  ADD CONSTRAINT chk_consent_granted_type
      CHECK ((type IN ('OPT_OUT') AND granted = false)
          OR (type NOT IN ('OPT_OUT')));

O último CHECK trava a combinação sem sentido type = 'OPT_OUT' AND granted = true.

Três regras de uso, que outras seções referenciam em vez de redefinir:

1. A coluna de contexto chama-se evidence, e é a única. Não existe consent_events.metadata, e as tabelas de anonimização e de retenção das Seções 20 e 22 citam policy_version e consent_text_hash, nunca text_version nem text_hash, que não existem. O início e o fim de pausa gravam type = 'PAUSE_STARTED' com granted = false e evidence = {"days": 7, "pausedUntil": "2026-09-02T06:00:00Z"}, e type = 'PAUSE_ENDED' com granted = true.
2. A grafia do reingresso é RE_OPT_IN, com sublinhados. REOPTIN não existe no enum e um INSERT com esse valor falha.
3. consent_text_hash é o SHA-256 do texto após normalização canônica: NFC, quebras de linha convertidas para \n, espaços em sequência colapsados em um e espaços removidos das pontas. A normalização torna o hash imune a reformatação do arquivo de textos — sem ela, um formatador de código reindentando o arquivo mudaria o hash de uma versão já apresentada e destruiria a prova de qual texto o titular leu.

6.6 Tabela sessions #

Sessões ativas de assinantes e administradores. É o registro que torna o JWT revogável. A semântica de autenticação está na Seção 8.8; aqui fica só a estrutura.

6.6.1 Índices #

6.6.2 Chaves estrangeiras #

6.6.3 Constraints CHECK #

ALTER TABLE sessions
  ADD CONSTRAINT chk_sessions_exactly_one_subject
      CHECK (num_nonnulls(subscriber_id, admin_user_id) = 1),
  ADD CONSTRAINT chk_sessions_subject_type_matches
      CHECK ((subject_type = 'SUBSCRIBER' AND subscriber_id IS NOT NULL)
          OR (subject_type = 'ADMIN'      AND admin_user_id IS NOT NULL)),
  ADD CONSTRAINT chk_sessions_role_matches_subject
      CHECK ((subject_type = 'SUBSCRIBER' AND role = 'SUBSCRIBER')
          OR (subject_type = 'ADMIN'      AND role IN ('EDITOR','ADMIN','OWNER'))),
  ADD CONSTRAINT chk_sessions_expiry CHECK (expires_at > issued_at),
  ADD CONSTRAINT chk_sessions_revoked_reason
      CHECK ((revoked_at IS NULL) = (revoked_reason IS NULL)),
  ADD CONSTRAINT chk_sessions_impersonation_scope
      CHECK ((impersonated_by_admin_id IS NULL) = (scope <> 'IMPERSONATION_READONLY')),
  ADD CONSTRAINT chk_sessions_impersonation_reason
      CHECK (impersonated_by_admin_id IS NULL
             OR (impersonation_reason IS NOT NULL
                 AND length(btrim(impersonation_reason)) >= 10)),
  ADD CONSTRAINT chk_sessions_restricted_is_subscriber
      CHECK (scope <> 'RESTRICTED' OR subject_type = 'SUBSCRIBER');

chk_sessions_impersonation_scope é a garantia estrutural de que impersonação é somente leitura: uma sessão com administrador impersonando é obrigatoriamente IMPERSONATION_READONLY, e o invólucro de API recusa todo POST, PATCH, PUT e DELETE nessa sessão antes de o handler existir. A trava vale para todas as rotas que alteram estado do assinante, sem exceção de prefixo — inclusive cancelamento de assinatura, troca de forma de pagamento, troca de plano, reenvio, pedido de eliminação e opt-out, que não vivem sob /api/me/. A verificação por handler continua existindo, como segunda camada, nunca como única.

6.7 Tabela otp_codes #

Códigos de uso único para login do assinante e verificações. Cobre tanto o OTP numérico do WhatsApp quanto o token do magic link por e-mail. A semântica está na Seção 8.2 e 8.3.

6.7.1 Índices #

6.7.2 Chaves estrangeiras #

delivery_message_log_id não é FK. message_logs é particionada e sua chave primária é composta (id, created_at), então uma FK simples por id não é declarável. A coluna é uma referência lógica, resolvida na aplicação. Isso está documentado em 6.19.4.

6.7.3 Constraints CHECK #

ALTER TABLE otp_codes
  ADD CONSTRAINT chk_otp_destination
      CHECK ((channel = 'WHATSAPP'   AND phone_e164 IS NOT NULL AND phone_hmac IS NOT NULL)
          OR (channel = 'EMAIL_LINK' AND email IS NOT NULL AND email_hmac IS NOT NULL)),
  ADD CONSTRAINT chk_otp_phone_envelope
      CHECK (phone_e164 IS NULL OR phone_e164 ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_otp_email_envelope
      CHECK (email IS NULL OR email ~ '^v[0-9]+:'),
  ADD CONSTRAINT chk_otp_phone_hmac
      CHECK (phone_hmac IS NULL OR phone_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_otp_email_hmac
      CHECK (email_hmac IS NULL OR email_hmac ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_otp_attempts CHECK (attempts >= 0 AND attempts <= max_attempts),
  ADD CONSTRAINT chk_otp_max_attempts CHECK (max_attempts BETWEEN 1 AND 10),
  ADD CONSTRAINT chk_otp_expiry CHECK (expires_at > created_at),
  ADD CONSTRAINT chk_otp_code_hash CHECK (code_hash ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_otp_single_terminal_state
      CHECK (consumed_at IS NULL OR invalidated_at IS NULL);

O último CHECK impede que um código esteja simultaneamente consumido e invalidado, o que tornaria ambígua a auditoria de "este código foi usado ou barrado?".

6.7.4 Tabela unsubscribe_tokens #

Tokens opacos de uso único do link público de descadastro, aquele que acompanha o rodapé do e-mail e a mensagem de confirmação. É a 28ª tabela do modelo e a última da lista fechada de 6.1.7. Esta subseção é a única dona da estrutura: a Seção 20, que é a dona do comportamento do opt-out, referencia daqui e não redefine coluna, tipo nem índice.

Ela não cabe em otp_codes: o token do descadastro não é um código de autenticação, não tem contador de tentativas, não tem canal de entrega próprio e a sua validade é de dias, e não de minutos. Reaproveitar otp_codes exigiria um valor novo no enum OtpPurpose e colunas que nunca seriam preenchidas — uma tabela própria é mais barata do que um enum poluído.

Sem updated_at: a linha nasce e, no máximo, recebe used_at uma vez.

Índices

Chave estrangeira

CASCADE aqui é o oposto do RESTRICT de consent_events, e por um motivo: o token não é prova de nada. Ele é uma credencial de curta vida; sumindo o titular, ela perde qualquer função e mantê-la só deixa um segredo vivo apontando para uma conta que não existe. A prova do descadastro fica em consent_events, com type = 'OPT_OUT', que é append-only.

Constraints CHECK

ALTER TABLE unsubscribe_tokens
  ADD CONSTRAINT chk_unsub_id_ulid CHECK (id ~ '^[0-9A-HJKMNP-TV-Z]{26}$'),
  ADD CONSTRAINT chk_unsub_token_hash CHECK (token_hash ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_unsub_expiry CHECK (expires_at > created_at),
  ADD CONSTRAINT chk_unsub_used_after_created
      CHECK (used_at IS NULL OR used_at >= created_at);

DDL completo, para a migration M4 (a criação da tabela e a FK) e para M10 e M11 (o índice parcial e os CHECK, que o Prisma não representa — 6.31.2):

CREATE TABLE unsubscribe_tokens (
  id            char(26)    NOT NULL,
  subscriber_id char(26)    NOT NULL,
  token_hash    char(64)    NOT NULL,
  created_at    timestamptz NOT NULL DEFAULT now(),
  expires_at    timestamptz NOT NULL,
  used_at       timestamptz,
  CONSTRAINT unsubscribe_tokens_pkey PRIMARY KEY (id),
  CONSTRAINT unsubscribe_tokens_subscriber_id_fkey
    FOREIGN KEY (subscriber_id) REFERENCES subscribers(id)
    ON DELETE CASCADE ON UPDATE CASCADE
);

CREATE UNIQUE INDEX uq_unsubscribe_token_hash
  ON unsubscribe_tokens (token_hash);
CREATE INDEX ix_unsubscribe_tokens_subscriber
  ON unsubscribe_tokens (subscriber_id, created_at DESC);
CREATE INDEX ix_unsubscribe_tokens_expiring
  ON unsubscribe_tokens (expires_at) WHERE used_at IS NULL;

Retenção. Expurgo físico 30 dias depois de expires_at, junto com o expurgo de otp_codes (6.33.1 e 6.33.2), e imediato em qualquer token do titular no momento em que o opt-out é gravado — quem já saiu não precisa de um link para sair de novo. Volume esperado em 1 ano, com 10.000 assinantes: cerca de 15.000 linhas.

6.8 Tabela admin_users #

Contas do painel administrativo. Não há autocadastro: contas nascem por seed ou por criação feita por outra conta com papel OWNER ou ADMIN.

6.8.1 Índices #

6.8.2 Chaves estrangeiras #

6.8.3 Constraints CHECK #

ALTER TABLE admin_users
  ADD CONSTRAINT chk_admin_role_not_subscriber CHECK (role <> 'SUBSCRIBER'),
  ADD CONSTRAINT chk_admin_email_shape CHECK (email ~ '^[^@[:space:]]+@[^@[:space:]]+\.[a-z]{2,}$'),
  ADD CONSTRAINT chk_admin_password_hash_argon2 CHECK (password_hash LIKE '$argon2id$%'),
  ADD CONSTRAINT chk_admin_failed_login CHECK (failed_login_count BETWEEN 0 AND 100),
  ADD CONSTRAINT chk_admin_totp_pair
      CHECK ((totp_secret_encrypted IS NULL AND totp_enrolled_at IS NULL)
          OR (totp_secret_encrypted IS NOT NULL));

Regra adicional garantida na aplicação, não no banco: sempre existe ao menos uma conta OWNER ativa. Tentativa de rebaixar ou desativar o último OWNER devolve OWNER_REQUIRED (Seção 7.11). Não é um CHECK porque a verificação é sobre o conjunto da tabela, não sobre a linha, e um trigger para isso criaria contenção no UPDATE.

6.8.4 Tabela admin_trusted_devices #

Dispositivos que o administrador marcou como confiáveis, dispensando o segundo fator em logins seguintes. É a 27ª tabela do modelo; a 28ª e última é unsubscribe_tokens (6.7.4).

Ela existe por um motivo específico: um fingerprint derivado de cabeçalhos não pode governar autenticação. O sessions.device_fingerprint é sha256 de user-agent, Accept-Language e plataforma declarada — três valores inteiramente controlados pelo cliente e de entropia baixíssima. Usar esse valor para dispensar o TOTP significaria que adivinhar a combinação de cabeçalhos mais comum entre administradores brasileiros (Chrome em Macintosh com pt-BR) burla o segundo fator com a senha na mão. O que dispensa o TOTP passa a ser um segredo emitido pelo servidor, guardado só como hash.

Índices

Chave estrangeira

Constraints CHECK

ALTER TABLE admin_trusted_devices
  ADD CONSTRAINT chk_trusted_token_hash CHECK (token_hash ~ '^[0-9a-f]{64}$'),
  ADD CONSTRAINT chk_trusted_expiry CHECK (expires_at > created_at);

Regras de uso, garantidas na aplicação:

1. A senha continua sendo exigida sempre. O cookie dispensa apenas o TOTP.
2. Toda a lista do administrador é apagada em qualquer troca de senha, em uso de código de recuperação e em logout-all.
3. sessions.device_fingerprint permanece exclusivamente como sinal informativo para a notificação de dispositivo novo, e é proibido usá-lo em qualquer decisão de autorização. Um teste de arquitetura falha se device_fingerprint for lido fora do módulo de notificação.

6.9 Tabela admin_audit_log #

Registro de toda ação administrativa que muda estado. É append-only na prática, com a mesma proteção de consent_events (ver 6.36.3).

Esta tabela tem um único esquema, e é o desta subseção. As Seções 13, 15 e 23, que listam campos da auditoria em tela, em exportação e em documentação de formato, usam exatamente os nomes e os tipos abaixo. A tabela é append-only com 5 anos de retenção: errar o nome de uma coluna aqui não é reversível por migration barata, então a lista de nomes proibidos ao final desta subseção é tão normativa quanto a própria tabela.

Nomes que não são colunas desta tabela, e que nenhuma seção pode citar como se fossem:

6.9.1 Índices #