teqo-backup/docs/plans/whatsapp-envio-liderancas.md
Francisco Ignácio Fontoura Solla adc0f31f5b Sync all project docs with the deployed remodel and hardening; compile roadmap
- 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.
2026-07-24 02:04:45 -03:00

104 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# D4 — Envio WhatsApp 1:1 para lideranças
Status: rascunho
Atualizado em: 2026-07-23
Item do roadmap: [docs/roadmap.md](../roadmap.md) (Trilha D, item D4; programa [whatsapp-interno-campanha.md](whatsapp-interno-campanha.md))
Impeccable: B — compose encaixado no CRM de liderança / detalhe (sem rota de “marketing blast”)
Appetite: ~1–2 dias eng; actions + UI compose + templates curtos; reusa sessão pessoal D3
Responsável: —
## Design (Impeccable)
Âncoras: `PRODUCT.md` (princípios 2, 3 Edit where you see, 4) / `DESIGN.md` (register `product`) · tema `campaign` · precedente `LeadershipInviteButtons` / share `wa.me`.
Na implementação: craft compacto → critique → polish.
Brief compacto:
- **Persona / contexto:** Assessor na estrada cobra atualização; CG manda um “como está Orolândia?” — a liderança deve ver a mensagem **no chat pessoal de sempre** com aquela pessoa.
- **Job principal:** enviar **uma** mensagem 1:1 pela **sessão WhatsApp do próprio ator** para **uma** liderança do escopo.
- **Estratégia de cor:** Restrained; ícone WA ok; primário Signal Red.
- **Edit where you see:** sim — Sheet “Mensagem” no detalhe `/campanha/liderancas/[id]`.
- **Anti-goals:** multi-destinatário; enviar pela sessão de outro staff; número institucional; templates de propaganda; matar `wa.me` de convites.
## Dados → decisão → apresentação
Dados: N/A — superfície de ação (compose). Feedback de entrega = Feel the action (§7), não KPI.
## Contexto
Com [D3](whatsapp-canal-fundacao.md), cada staff tem (ou não) a própria sessão pareada. O valor de produto é: **parece Zap pessoal** — a liderança não “fala com a campanha”, fala com o assessor/CG que já conhece.
## Objetivos
- Action `sendLeadershipWhatsappMessage({ leadershipId, body })`: access OK → resolve phone → exige **`whatsappSession` do `req.user` em `connected`** + Consent → `enqueueSend(actorUserId, …)` → log outbound com `user` = ator.
- UI compose: textarea + templates curtos editáveis; se sessão down → CTA “Conectar meu WhatsApp” (perfil D3) **e** fallback `wa.me` (“Abrir no seu WhatsApp”).
- Rate limit por ator/hora e por destinatário; **hard reject** N>1 destinatários.
- Guardrails: só `coordinator`/`advisor`; advisor só lideranças dos municípios acessíveis; nunca `supporter`; nunca enviar usando sessão de terceiro.
## Decisões travadas
- **Remetente = sessão do ator logado.** A liderança recebe do número pessoal pareado daquela pessoa. **Rejeitado:** “enviar como campanha”; CG disparar pelo chip de um assessor; escolher remetente na UI.
- **Um destinatário por envio.** **Rejeitado:** lista/BCC; “todas as lideranças do município”.
- **Escopo = access da liderança.** **Rejeitado:** telefone livre digitado.
- **`wa.me` = fallback + convites.** **Rejeitado:** migrar convites para o bridge nesta fatia.
- **i18n/naming:** `sendLeadershipWhatsappMessage`, `LeadershipWhatsappCompose`; copy pt-BR (“Enviar pelo meu WhatsApp”).
## Questões em aberto
- **Templates: hardcoded vs collection?** **Opções:** 3–5 strings em código | collection. **Recomendação:** constantes na v1.
- **Thread no detalhe?** **Opções:** só compose | compose + últimas N do par **nesta sessão**. **Recomendação:** últimas 10 msgs do par na sessão do ator (não misturar threads de outro assessor). _(assumido)_
## Abordagem proposta
```mermaid
flowchart LR
UI["LeadershipWhatsappCompose"]
Action["sendLeadershipWhatsappMessage"]
Sess["whatsappSession do ator"]
Bridge["enqueueSend(actorId, …)"]
Log["whatsappMessage outbound"]
Lead["leadership phone"]
UI --> Action
Action --> Sess
Action --> Lead
Action --> Bridge --> Log
```
Componentes:
- **`LeadershipWhatsappCompose`**: Sheet; estados connected / needs-pairing / sending / failed; deep-link perfil se unpaired.
- **Action** em `actions/whatsapp.ts`: `overrideAccess: false`; nunca aceita `sessionUserId` do client (só `req.user.id`).
- **Reuse D3:** bridge, session, Consent, phone normalize.
- **Migration:** nenhuma se D3 já tem `user` no log.
## Dependências
- **Dura:** **D3** (sessão pessoal + log + Consent).
- **Suave:** telefones reais nas lideranças.
## Não escopo
- Inbox / rascunhos → [D5](whatsapp-sugestao-atualizacoes.md).
- Apoiadores / grupos / auto-resposta → fora.
- Push “mensagem enviada” → D2.
## Rabbit holes
- **Templates ricos.** Mitigação: `{nome}`, `{praca}` no máximo.
- **Fila com retry infinito.** Mitigação: retry curto + `failed` visível.
## Adiado com gatilho
- Bulk UI. Revisitar só com ok jurídico explícito.
- CG enviar “em cópia” vendo thread do assessor. Revisitar com o item de inbox agregado do programa (acesso cruzado).
## Referências
- [whatsapp-interno-campanha.md](whatsapp-interno-campanha.md), [whatsapp-canal-fundacao.md](whatsapp-canal-fundacao.md)
- `src/components/campaign/LeadershipInviteButtons.tsx`
- `src/app/(campaign)/campanha/(app)/liderancas/[id]/page.tsx`
- `src/utilities/campaignAccess.ts`, `phone.ts`
- `PRODUCT.md` / `DESIGN.md`
- AGENTS.md — access, transactions