- Compile docs/roadmap.md into a next-steps document (277→206 lines): R0–R5/M1–M5 tables and the delivered map/list item paragraphs compressed into 'Já entregue'; janelas, grafo and cortes list only open IDs; C10/C11/C8 fill-ins keep their original triggers; C5 moved under 'A validar'. - Record the production deploy of the destructive remodel chain (2026-07-23 Vercel builds) across roadmap, AGENTS.md, the project notebook and plans — supersedes every 'deploy pendente'; smoke pós-deploy + onboarding remain the open blockers. - Fix AGENTS.md internal contradictions: Município locked-decisions bullet (435, Camaçari whole, candidate role), campaignUser role enum, deploy-checklist item 7 as historical, access/* structure note, election-aggregates artifact + election-tse revalidate runbook. - Sync open plans to real identifiers (plaza*/nucleus* → municipality*): the intelligence program (master + E8–E15/B13/C12 with artifact/caching context and satisfied deps), B8 rescoped to Salvador ZE 1–19 only, WhatsApp D3–D5, D2, A6 (now the insight layer over stateDeputy), RS+, onda-0 smoke step. - Close items verified done in code: C8 F4 (DRY de forms) complete, filtros-auto shared pending shell, petition generateStaticParams select/depth; ledger the surviving user-visible 'Praça' copy in src as new P2 debt. - Banner delivered praça-era plans (production note + rename pointer); mark remodelagem-pracas.md superseded and remodelagem-municipios.md delivered. - TECH-DEBT smell statuses, TESTING RBAC row, README quality gates, campanha UI rules updated to current component names.
8.4 KiB
D3 — Fundação do canal WhatsApp interno
Status: rascunho Atualizado em: 2026-07-23 Item do roadmap: docs/roadmap.md (Trilha D, item D3; programa whatsapp-interno-campanha.md) Impeccable: B — pareamento QR self-service por staff (sem inbox/compose de produto) Appetite: ~3 dias eng; sidecar multi-sessão + migration + Consent + UI QR/status; sem envio/inbox de produto Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md (princípios 1 soberania, 2 clareza, 4 depth/simplicity) / DESIGN.md (register product) · tema data-theme='campaign' · shells CampaignPageShell · superfície de perfil existente (/campanha/perfil se houver).
Na implementação (implement-roadmap-item): craft compacto → critique → polish (fluxo QR + estados; sem redesign de CRM).
Brief compacto:
- Persona / contexto: Assessor ou Coordenador Geral no celular/notebook quer ligar o próprio Zap uma vez e seguir falando com lideranças “como sempre” — só que o Teqo passa a enxergar o fio.
- Job principal: parear a conta WhatsApp pessoal do
campaignUservia QR no app e manter a sessão viva no sidecar. - Estratégia de cor: Restrained; sessão caída =
destructive/cadence-overdue; aviso ToS em muted, não modal de terror. - Edit where you see: pairing self-service no perfil do staff (ação rara); não no CRM de lideranças.
- Anti-goals: número institucional único; admin pareando o chip de outra pessoa; chat UI; inbox; sync de histórico completo; esconder risco ToS/ban.
Dados → decisão → apresentação
- Vou apresentar dados? Sim, superfície mínima neste item (status da minha sessão).
- Decisões desbloqueadas:
- Assessor/CG: “meu WhatsApp está conectado ao Teqo? preciso escanear de novo?”
- (Aggregate para D4/D5: sessão do ator healthy → habilitar compose/inbox daquela pessoa.)
- Forma escolhida: número + contexto (estado
conectado | aguardando QR | erro+ telefone mascarado da conta pareada +lastSeenAt). Rejeitado: dashboard de N sessões para o time inteiro na v1 (CG pode ter lista read-only “quem conectou” — Adiado); chart de uptime; KPI de conversas. - Profile: categórico; 1 sessão por
campaignUserstaff. - Anti-goals de dado: sem vanity de volume de msgs nesta fatia.
Contexto
O programa exige que a liderança continue vendo o Zap pessoal do assessor/CG — não um robô institucional. Isso implica N sessões (uma por staff), pareadas no app (QR), não um chip compartilhado.
Socket WhatsApp não roda em Vercel serverless → sidecar multi-sessão. Sem fundação (sessão↔ campaignUser, adapter, log, Consent), D4/D5 não têm onde plugar.
Objetivos
- Sidecar Node longo com um adapter não oficial, N sessões indexadas por
campaignUser.id(só rolescoordinator|advisor). - Fluxo de pareamento no
/campanha:startPairing→ sidecar gera QR → UI mostra QR (refresh se expirar) → eventopaired→ statusconnected+ telefone detectado (normalizado). - App Next.js ↔ sidecar via API autenticada (HMAC); o Next não abre socket WA.
- Collections:
whatsappSession(1:1 comcampaignUser, unique) +whatsappMessage(log comsession/campaignUser, direção, phones, texto, timestamps, match opcionalleadership). - Consent
campanha-whatsapp-canal(fail-closed) + aceite explícito no UI de pairing (risco ToS/conta pessoal). Texto no lote jurídico. - UI: status + QR + desconectar só da própria sessão;
leadernão pareia. - Guardrails: allowlist inbound = phones de lideranças engajadas no CRM (e, para advisor, preferir as dos municípios acessíveis — pode afrouxar para “todas lideranças engajadas” se match for só por phone); rate limit por sessão; secrets em env.
Decisões travadas
- Sessão =
campaignUserstaff, número pessoal. UNIQUE(campaignUser). Rejeitado: sessão singleton institucional; parear número digitado sem QR; um CG operar o chip de um assessor. - Login/pareamento = QR no app (estilo WhatsApp Web). Rejeitado: só deep-link
wa.me; pairing por SMS inventado; exigir app Companion oficial da Meta como único caminho (se o adapter oferecer código de pareamento sem QR como fallback técnico, ok — UX primária = QR). - Sidecar multi-sessão fora do Vercel. Credenciais por sessão em volume do worker. Rejeitado: Baileys dentro de Server Action; Cloud API / WABA.
- Um adapter na v1. Baileys ou Evolution self-hosted — um só. Rejeitado: multi-provider.
- Log mínimo pós-
pairedAt; sem histórico prévio; sem mídia binária na v1. Rejeitado: dump completo do chip; gravar chats com não-CRM. - Consent
campanha-whatsapp-canal+ copy de risco pessoal. Rejeitado: hardcode de ID; silêncio sobre ban/ToS. - i18n/naming:
whatsappSession,whatsappMessage,startWhatsappPairing,whatsappBridge; UI pt-BR (“Conectar meu WhatsApp”, “Escaneie o QR com o celular”).
Questões em aberto
- Onde hospedar o sidecar? Opções: Fly.io / Railway / VPS. Recomendação: Fly/Railway com volume; runbook na implementação. (ops)
- CG vê quem do time está conectado? Opções: não na v1 | lista read-only de status. Recomendação: não na v1 (só a própria sessão); lista de saúde do time = Adiado com gatilho no programa.
Abordagem proposta
flowchart LR
Staff["Assessor / CG<br/>/campanha/perfil"]
QR["QR pairing<br/>própria sessão"]
Next["Next.js<br/>HMAC + queue"]
Worker["Sidecar<br/>N sessões WA"]
Sess["whatsappSession<br/>1:1 campaignUser"]
Log["whatsappMessage"]
CRM["leadership via phone"]
Staff --> QR --> Next
Next <--> Worker
Worker --> Sess
Worker --> Log
Log --> CRM
Componentes:
whatsappBridge(src/utilities/whatsappBridge.ts,server-only):startPairing(userId),getSessionStatus(userId),disconnect(userId), (D4)enqueueSend(userId, …); timeout curto.- Sidecar (
workers/whatsapp-bridge/): mapcampaignUserId → adapter session; emite QR/status/inbound; allowlist CRM. whatsappSession:user→campaignUser(unique, required),status,pairedPhone,pairedAt,lastSeenAt,lastError.whatsappMessage:session/user,direction,peerPhone,leadership(nullable),body,providerMessageId, timestamps.- UI
WhatsappPairingPanelno perfil: QR image/data-URL ou SVG, polling/SSE de status, botão desconectar, aviso Consent/ToS. - Actions
startWhatsappPairing/disconnectWhatsappSession/getWhatsappSessionStatus— actor só na própria sessão (user.id). - Migration:
pnpm migrate:create add_whatsapp_channel— session + message; sem backfill. - Reuse:
normalizeBrazilianPhone,campaignConsent,withPayloadTransaction,overrideAccess: false.
Dependências
- Dura: remodelagem deployada (
campaignUserroles +leadership/Contact). - Suave: Onda 0 (texto Consent); telefones reais nas lideranças.
- Não depende de D2.
Não escopo
- Compose/envio → D4.
- Inbox / rascunhos → D5.
- Número institucional / WABA / massa → fora.
- Mídia no log; grupos; histórico pré-pairing → Adiado.
Rabbit holes
- N sockets × memória no worker. Mitigação: lazy connect on pairing; disconnect idle com re-QR; monitorar RSS antes de escalar horizontalmente (sticky sessions por user se shardear — Adiado).
- Staff desconecta no celular e o Teqo não sabe. Mitigação: health ping + status
erro+ CTA re-parear no compose D4. - Parear conta errada (pessoal demais / família). Mitigação: mostrar telefone detectado pós-QR + “Desconectar”; copy de que deve ser o número que as lideranças já usam.
Adiado com gatilho
- Retention/expurgo do log. Revisitar quando: volume ou pedido jurídico.
- Lista CG “quem conectou”. Revisitar quando: onboarding do time travar sem visão de cobertura.
- Advisor-only allowlist por município no inbound. Revisitar se falso positivo de match cruzado aparecer.
Referências
- whatsapp-interno-campanha.md
docs/roadmap.md— Trilha Dsrc/utilities/phone.ts,campaignConsent.ts,campaignAccess.tsdocs/plans/notifications.md— D2PRODUCT.md/DESIGN.md- AGENTS.md — Consent, migrations, campaign auth