Replace all project-local .cursor/ path references with .agents/ across rules, skills, environment config, hooks, and ignore files. Keep Cursor editor paths (~/.cursor/, window.cursor, CURSOR_API_KEY) and vendored Impeccable editor-hook paths unchanged.
14 KiB
Convite por WhatsApp na lista de lideranças
Status: entregue
Atualizado em: 2026-07-26
Item do roadmap: docs/roadmap.md (Trilha B, item B30)
Impeccable: B — encaixe de uma ação na tabela existente de /campanha/liderancas
Appetite: ~0,25–0,5 dia eng; zero migration/collection/action nova; um componente client encaixado na coluna actions existente (B28 ✓)
Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md (register Field Desk) · tema data-theme='campaign' · princípios campanha-edit-where-you-see.mdc e campanha-action-feedback.mdc.
Na implementação (implement-roadmap-item): craft compacto → critique → polish (a UI já existe em dois lugares — LeadershipInviteButtons.tsx no detalhe e o ícone de WhatsApp em AdvisorsTable.tsx / coluna actions do B28 — este item compõe convite + contato na mesma célula).
Brief compacto:
- Persona / contexto: Coordenador/assessor varrendo a lista de lideranças para cobrar cadastro incompleto, sem querer abrir cada ficha.
- Job principal: disparar o convite de completar cadastro por WhatsApp sem saltar de tela.
- Estratégia de cor: Restrained (default) — botão ghost/ícone, sem cor de destaque nova.
- Edit where you see: sim — ação existente (
createCampaignInvite) fica disponível na própria linha, mas não é edição de campo (é disparo de ação one-shot com efeito colateral externo — abrir link). Por isso o padrão aplicável é o two-step reveal já usado no detalhe (gerar → depois um link real para o usuário clicar), não auto-save. - Anti-goals: não reabrir o formulário completo de convites (dois botões, login+autopreenchimento) dentro da linha — só o convite de completar cadastro, que é o pedido; não usar
window.openimediato pós-await (risco de popup blocker, ver Decisões travadas).
Dados → decisão → apresentação
Dados: N/A — item é uma ação de disparo (convite), não introduz métrica, série, mapa ou agregado novo.
Contexto
/campanha/liderancas (src/app/(campaign)/campanha/(app)/liderancas/page.tsx) já lista lideranças numa CampaignTable (Pass 2 W1 — leadershipColumns(stateDeputyOptions)). Colunas atuais (pós-B28 ✓ / B31 ✓): name | email | phone | supportStatus | municipalities | organizations | stateDeputies | appAccess | actions (WhatsApp de contato MessageCircleIcon + whatsAppHrefForPhone). LeadershipRowViewModel (src/utilities/leadershipData.ts) já expõe phone: string | null por linha — não falta nenhum dado no loader.
A funcionalidade "convidar para completar cadastro por WhatsApp" já existe e funciona, mas só no detalhe (/campanha/liderancas/[id]), via LeadershipInviteButtons (src/components/campaign/invite/LeadershipInviteButtons.tsx): chama a server action createCampaignInvite (src/app/(campaign)/campanha/actions/invite.ts → createCampaignInviteForActor em src/utilities/campaignInviteCreation.ts), que cria um campaignInvite com token único (generateCampaignInviteToken, expira em 7 dias) e monta a URL do WhatsApp (buildCampaignInviteWhatsAppLink em src/utilities/campaignInvite.ts → buildWhatsAppUrl em src/lib/phone.ts). Se contact.phone estiver vazio, a action lança Error('Cadastre o celular da liderança antes de gerar o convite.') — hoje só validado no servidor; o botão do detalhe nunca desabilita por telefone.
Existe um precedente de ícone de ação por linha com disable por telefone inválido: AdvisorsTable.tsx (src/components/campaign/advisor/AdvisorsTable.tsx, linhas ~411–437) — calcula whatsAppHrefForPhone(row.phone) com normalizeBrazilianPhone (src/lib/phone.ts) e renderiza um Button variant="ghost" size="icon" com MessageCircleIcon, ativo (âncora wa.me) ou disabled com aria-label explicando a ausência de celular. Esse é o padrão de disable pedido pelo usuário — falta compor com a geração de convite (que a AdvisorsTable não tem, porque ali o wa.me é só um atalho de contato, sem token).
Pedido de produto (2026-07-25): adicionar, ao fim de cada linha de /campanha/liderancas, uma ação rápida que dispare esse mesmo convite (kind: 'autopreenchimento') sem precisar abrir a ficha, desabilitada quando a liderança não tem celular válido.
Coincide no tempo com o item B28 (mesma leva de pedidos de produto de 2026-07-25 — email-celular-lista-liderancas.md), que também adiciona uma ação de WhatsApp por linha na mesma tabela, mas com intenção diferente: o ícone do B28 é o atalho de contato genérico já usado em AdvisorsTable (wa.me sem mensagem/token — "falar com esta pessoa agora"), enquanto este item é o disparo do convite de completar cadastro (gera campaignInvite com token e mensagem pronta). São duas ações distintas que, se ambas chegarem à mesma linha, precisam coexistir sem confundir o operador — por isso a coordenação de layout é uma decisão travada abaixo, e a dependência entre os dois itens é suave (qualquer um pode ir primeiro).
Objetivos
- Encaixar na coluna
actionsexistente (B28 ✓) uma ação de "Convidar para completar cadastro (WhatsApp)" por linha, ao lado do atalho de contato. - Reusa a mesma server action
createCampaignInvitee o mesmokind: 'autopreenchimento'já usados no detalhe — nenhuma regra de negócio nova, nenhuma mudança de access (src/utilities/access/invites.tsjá escopa advisor a lideranças acessíveis). - Botão desabilitado quando
row.phonefornullou não passar emnormalizeBrazilianPhone(mesmo critério doAdvisorsTable), comaria-label/tooltip explicando o motivo. - Sem migration, sem collection nova, sem endpoint novo.
Decisões travadas
- Two-step reveal (gerar → depois um
<a>real de "Enviar pelo WhatsApp") em vez dewindow.openautomático pós-await. O convite exige uma chamada de servidor (criação de token) antes de existir a URL do WhatsApp; abrir a aba automaticamente depois de umawaitquebra o vínculo síncrono com o gesto do usuário e é bloqueado por popup blockers em Safari/Firefox com frequência. O próprio detalhe (LeadershipInviteButtons) já resolve isso mostrando umAlertcom um link real depois de gerar — este item replica o mesmo contrato, só compactado numPopoverdisparado pela linha. Rejeitado:window.open(whatsappUrl, '_blank')direto após oawaitda action — risco de bloqueio silencioso, sem precedente no código; o usuário não teria como saber que nada abriu. - Reusar
createCampaignInvite/kind: 'autopreenchimento'sem tocar na action, no schema ou na collectioncampaignInvite. É exatamente a mesma operação já usada no detalhe (mesmo consentimento fail-closed, mesmo token, mesma expiração) — criar uma segunda entrada de convite seria duplicar sem motivo. Rejeitado: action dedicada "quick invite" — não há diferença de contrato que justifique um segundo caminho. - Critério de "celular válido" =
normalizeBrazilianPhone(row.phone)retorna não-nulo, o mesmo helper já usado emAdvisorsTable.tsxe dentro debuildWhatsAppUrl. Rejeitado: checar sóBoolean(row.phone)— aceitaria strings malformadas que a action rejeitaria de qualquer forma no servidor, produzindo um botão "ativo" que sempre falha. - i18n e naming: identificadores em inglês — componente
LeadershipInviteRowAction(src/components/campaign/invite/LeadershipInviteRowAction.tsx); strings visíveis em pt-BR ("Convidar por WhatsApp", "Sem celular cadastrado"). - Ícone distinto do WhatsApp de contato do B28. Como as duas ações coexistem na mesma célula
actions, o ícone deste item éUserPlusIcon(nãoMessageCircleIcon) comaria-labelexplícito ("Convidar {nome} para completar cadastro por WhatsApp"). Rejeitado: mesmo ícone dos dois itens — ambíguo sobre qual ação cada clique dispara.
Questões em aberto
(Fechadas na revisão 2026-07-26 — defaults adotados na implementação.)
- Visibilidade da ação: A — renderizar para todo staff que vê a linha; access na
createCampaignInvite. - Ícone compacto: B —
UserPlusIcon+aria-labelcompleto, densidade da tabela.
Abordagem proposta
flowchart LR
Row[Linha da tabela<br/>leadershipColumns] --> Action[LeadershipInviteRowAction<br/>client island]
Action -->|phone inválido| Disabled[Botão disabled<br/>aria-label explica]
Action -->|clique| Popover[Popover: Convidar por WhatsApp]
Popover -->|gerar| Invite[createCampaignInvite<br/>kind: autopreenchimento]
Invite --> Result[Alert com<br/>âncora Enviar pelo WhatsApp]
Componentes:
LeadershipInviteRowAction(novo,src/components/campaign/invite/LeadershipInviteRowAction.tsx, client): recebeleadershipID: number,name: string,phone: string | null. Calcula validade comnormalizeBrazilianPhone. TriggerButton variant="ghost" size="icon"comUserPlusIcon,disabledquando telefone inválido. Popover replica o fluxo deLeadershipInviteButtonssó parakind: 'autopreenchimento'—useTransition+createCampaignInvite+ Alert com âncorawhatsappUrle "Copiar link".leadershipColumns→ célulaid: 'actions':inline-flex justify-end gap-1comLeadershipInviteRowAction+ botão WhatsApp de contato do B28 (inalterado em comportamento).- Sem migration, sem collection, sem server action nova, sem endpoint.
Revisão 2026-07-26: auditoria pré-implementação achou o plano defasado (coluna inviteAction separada e contagem de colunas pré-B28/B31); as-built encaixa na coluna actions com UserPlusIcon. Entregue em código (2026-07-26): LeadershipInviteRowAction + testes em campaignInviteInteractions.unit.spec.ts; gate tsc/lint/format/cycles/532 unit/406 int; pnpm build não rodou neste worktree (falta PAYLOAD_SECRET); knip P3 pré-existente. Pós-/simplify (mesmo dia): disable via hasValidPhone (mesmo critério que whatsAppHrefForPhone na célula); erros de convite em src/lib/campaignInviteClient.ts (mapCreateCampaignInviteError + constante compartilhada com campaignInviteCreation).
Dependências
- Soft: B28 (e-mail + celular na lista de lideranças, plano) — mesma tabela, mesma área de ação por linha; qualquer um dos dois pode ir primeiro, mas quem chegar depois precisa acomodar o ícone do outro na mesma célula/coluna de ações (ver Decisão "ícone distinto" acima). Não é dependência dura: este item não precisa das colunas E-mail/Celular do B28 para funcionar (já tem
phoneno view model hoje). - Reusa integralmente, sem depender de nenhum plano aberto:
createCampaignInvite(src/app/(campaign)/campanha/actions/invite.ts),campaignInvitecollection + access (src/collections/CampaignInvite.ts,src/utilities/access/invites.ts),buildWhatsAppUrl/normalizeBrazilianPhone(src/lib/phone.ts),LeadershipRowViewModel.phone(src/utilities/leadershipData.ts),CampaignTable/CampaignTableHead(src/components/campaign/shared/CampaignTable.tsx),Popover(src/components/ui).
Não escopo
- Convite de acesso ao app (
kind: 'login') na lista — só existe no detalhe hoje (condicionado asupportStatus === 'engajado'); o pedido do usuário é só o convite de completar cadastro. Se precisar, é extensão trivial do mesmo componente, mas fora deste item. - Disparo em massa / seleção múltipla de lideranças para convite em lote — vedado por Res. TSE 23.610 art. 33 e fora do desenho do produto (ver
docs/roadmap.md§ Fora de escopo); esta ação é sempre 1:1, uma linha por vez. - Editar/validar o telefone da liderança a partir da lista — isso é o formulário de edição existente (
/campanha/liderancas/[id]/editarou equivalente); esta ação só lêcontact.phone. - Bridge WhatsApp / sessão pareada (D3–D5 descartados) — este item usa só
wa.me1:1.
Rabbit holes
- "Já que estou na linha, deixa eu também mostrar o link/texto copiável direto na célula, sem Popover." Empilhar
Alert+ duas ações (WhatsApp + copiar link) dentro de uma célula de tabela quebra a densidade das outras 434 linhas quando várias forem abertas ao mesmo tempo. Mitigação: manter o resultado dentro doPopover(fecha ao clicar fora, como qualquer Popover do B9), nunca inline na célula. - "Vou generalizar para um
RowActionMenugenérico já que estou tocando a tabela." Um único botão não justifica um menu de ações genérico (regra do depth check — menos de 3 usos). Mitigação: um componente nomeado (LeadershipInviteRowAction), sem abstração de menu.
Adiado com gatilho
- Convite de acesso ao app (
kind: 'login') também na lista. Revisitar se o coordenador pedir a mesma ação para liderançasengajadosem abrir o detalhe — nesse ponto o componente já criado aqui vira a base (um segundo trigger no mesmo Popover). CampaignInviteDeliveryAlertcompartilhado (Alert + WhatsApp + copiar link). Só após um 3º call site além deLeadershipInviteButtonseLeadershipInviteRowAction(regra depth check).- Unificar string
MISSING_CONSENTemcampaignInviteRedemption/ defaults decampaignConsent. No próximo toque nesses módulos; constante canônica já vive emcampaignInviteClient.ts.
Referências
docs/roadmap.md(Trilha B, item B30 — § "Próximos — Campanha")src/app/(campaign)/campanha/(app)/liderancas/page.tsx—leadershipColumns, ponto de inserção da colunasrc/utilities/leadershipData.ts—LeadershipRowViewModel.phonesrc/components/campaign/invite/LeadershipInviteButtons.tsx— fluxo de referência (gerar → Alert com âncora)src/app/(campaign)/campanha/actions/invite.ts,src/utilities/campaignInviteCreation.ts,src/utilities/campaignInvite.ts— action + criação de convite + montagem do linksrc/lib/phone.ts—normalizeBrazilianPhone,buildWhatsAppUrlsrc/components/campaign/advisor/AdvisorsTable.tsx(linhas ~86–93, ~411–437) — precedente de ícone de linha com disable por telefonetests/unit/campaignInviteInteractions.unit.spec.ts,tests/int/campaignInvite.int.spec.ts— padrão de teste da action/UI de convite existente- AGENTS.md — Local API
overrideAccess: false(já respeitado pela action reusada), Campaign auth PRODUCT.md/.agents/rules/campanha-edit-where-you-see.mdc,.agents/rules/campanha-action-feedback.mdc— princípios de UI herdados