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

5.1 KiB
Raw Blame History

D4 — Envio WhatsApp 1:1 para lideranças

Status: rascunho Atualizado em: 2026-07-23 Item do roadmap: docs/roadmap.md (Trilha D, item D4; programa 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, 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

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.
  • 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