teqo-backup/docs/plans/pessoas-lista-unificada.md

8.7 KiB
Raw Blame History

Pessoas: lista unificada de pessoas da campanha

Status: rascunho Atualizado em: 2026-08-09 Issue: #495 Priority: P1 Model: composer-2.5 Impeccable: C — fluxo novo: nova rota + tabela + omnibox + filtros salvos Canvas UI: /home/fsolla/.cursor/projects/home-fsolla-Code-teqo/canvases/plan-c100-ui-draft.canvas.tsx Appetite: ~3–4 dias eng Responsável: —

Intenção

A mesa (coordenação e assessores) precisa ver todas as pessoas da campanha num lugar só — lideranças, dobradinhas e staff — sem saltar entre /liderancas, /dobradinhas e /assessores. A mesma pessoa com vários papéis aparece uma vez, com as capacidades expressas por território — não por uma coluna de "papel".

Persona e fluxo

  • Persona / contexto: coordenador/assessor na mesa (staff).
  • Job principal: encontrar a pessoa e ver, num relance, onde ela atua (assessora / liderança / dobradinha) e em quais municípios — e refinar o recorte.
  • Fluxo desejado: abre /campanha/pessoas → vê as pessoas com as colunas territoriais → filtra na omnibox (capacidade, município) → salva o recorte como atalho (mesmo padrão de Municípios, B18).
  • Anti-goals de produto: não vira spreadsheet mode; não é segundo cadastro de pessoa (a ficha continua sendo Contact); não substitui as listas especializadas.

Decisões de produto (travadas com o humano em 2026-08-09)

  • Colunas: Nome (com partido entre parênteses quando a pessoa é dobradinha com partido — ex. "Maria (PT)"), Contato (telefone em destaque + e-mail como segunda linha discreta; sem telefone, o e-mail vira a linha principal), Assessora (municípios da carteira), Lidera (municípios da liderança), Aliada em (municípios com dobradinha), Assessorado (assessores responsáveis — dobradinha e liderança), Base (cidade do Contact quando houver) e Ações (sem título: WhatsApp wa.me só para quem tem telefone + convite de cadastro na plataforma + apagar pessoa). Sem coluna de papel/kind; sem coluna de partido.
  • Sem apoiadores na lista (v1). /apoiadores permanece e continua sendo a superfície deles.
  • Merge por Contact: uma pessoa física = uma linha; capacidades = colunas preenchidas. Coordenador/candidato entram pela carteira real (municipality.advisors); coluna vazia = não assessora.
  • Facets da omnibox derivam das colunas: "É assessora / É liderança / É dobradinha" + filtros de município (e os filtros já existentes por domínio, ex. status de apoio em lideranças).
  • Outras listas permanecem. A lista de Municípios é a referência estrutural (omnibox, filtros salvos, colunas).

Objetivo e aceite

  • /campanha/pessoas lista e filtra pessoas com as 8 colunas; a mesma pessoa em 2+ papéis = 1 linha.
  • Ações: WhatsApp (wa.me) apenas quando há telefone registrado no Contact; quem não tem telefone não tem ação.
  • Ações: convite de cadastro na plataforma reusa o fluxo autopreenchimento das lideranças (createCampaignInvite + LeadershipInviteRowAction, consent fail-closed), disponível para quem tem engajamento de liderança; sempre 1:1 por linha (Res. TSE 23.610 art. 33 — sem disparo em massa).
  • Ações: Apagar pessoa — cascata destrutiva transacional (ficha Contact + liderança + votos declarados + dobradinha + apoiadores + convites + conta de acesso vinculada), precedida de confirmação explícita que lista tudo o que será removido; contas de coordenação/candidato nunca apagáveis.
  • Filtros salvos funcionam no padrão B18 (localStorage + submenu no sidebar), especializados para Pessoas — 2º call site do padrão, sem genericizar (FD2 vetou o sistema genérico).
  • Escopo de acesso preservado: assessor vê só a carteira dele; leader não acessa (rota staff, lockdown).
  • Nenhuma rota existente muda; /apoiadores, /liderancas, /dobradinhas, /assessores intactos.

Dados (intenção)

  • Vou apresentar dados? Não — as colunas expressam vínculos (território/partido), não métricas. Nenhum agregado de pessoa entra na superfície.

Direção no codebase (hipótese)

  • Áreas prováveis: rota nova src/app/(campaign)/campanha/(app)/pessoas/; shells do Pass 2 W1 (URL state, omnibox, tabela, paginação); utilitários por domínio existentes (leadership/stateDeputy/advisor); padrão B18 (municipalitySavedFilters.ts, listQueryMatch.ts); chips de relação (B159); entrada no sidebar.
  • Precedente a olhar: lista de Municípios (referência), B91 (busca global multi-entidade como agregador), B18 (filtros salvos), B159 (colunas de relação), B17 (seletor de colunas para conter a largura), share kit wa.me de apoiadores (precedente do botão Ações).
  • Risco de acoplamento: o merge por Contact no servidor deve aplicar o escopo de acesso por capacidade (cada query com o where existente do domínio) — nunca um escopo alargado; leader lockdown é o limite da rota.

Dependências

  • C99 (pessoas-identidade-contact.md) — sem o vínculo campaignUser → Contact e o campo de assessores responsáveis da liderança, as colunas Assessorado e Ações não completam.

Fora de escopo

  • Apoiadores na lista — revisitar pós-eleição, junto da multi-tenancy.
  • Remover as listas atuais; filtros salvos genéricos ou sincronizados no servidor; dedupe de Contact duplicados existentes (linhas duplicadas visíveis e aceitas no v1); rota para leader; entidade campaign.

Rabbit holes de produto

  • Genericizar filtros salvos. FD2 já vetou; o padrão B18 é o teto. Corte: especializar (2º call site do padrão).
  • Incluir apoiadores "para completar". A lista perde o foco e o merge fica mais caro. Corte: v1 sem; revisitar com evidência de uso.
  • Coluna de partido própria. O humano cortou — partido só como sufixo do nome.
  • Células com muitos municípios. Chips truncados com "+N" (padrão B159) e colapso mobile (B172).
  • Cascata de apagar esquecer uma relação. Cada relação com FK necessária (votos, convites, conta de acesso) precisa de passo explícito na transação — a coleção campaignUser já traz hooks de cascata (passkeys/notificações); o executor mapeia o resto com migrate:status/drizzle e testa o caminho completo em int.
  • "Mesclar pessoas" vira escopo. Transferir engajamentos entre fichas (ex. reancorar dobradinha) é campo admin hoje (stateDeputy.contact system-level); ferramenta de merge real é pós-eleição. Corte: v1 só copia campos da ficha + Apagar.

Questões em aberto (produto)

  • Pessoas sem nenhum papel (Contact puro, sem capacidade): entram na lista? Recomendação: não no v1 — sem capacidade não há linha; continua sendo assunto do admin Payload. (assumido — validar no gate)
  • Partido no nome: única fonte stateDeputy.party (quem não é dobradinha não tem sufixo). Recomendação: sim. (assumido — validar no gate)
  • Convite para dobradinhas/staff? Hoje o convite de cadastro existe só para lideranças (campaignInvite ancorado em leadership); assessores entram por provisionamento direto, sem convite. Recomendação: na v1, convite só nas linhas com engajamento de liderança; generalizar o convite para pessoa (ancorar em Contact) é mudança de schema do campaignInvite — follow-up pós-eleição. (assumido — validar no gate)
  • Quem pode apagar pessoa? Recomendação: coordenação/candidato (ação destrutiva transversal, maior que o escopo de carteira de assessor). (assumido — validar no gate)
  • Votos declarados na cascata: apagar junto (lista explícita no diálogo) vs bloquear enquanto existirem? Recomendação: apagar junto, listado no diálogo de confirmação — o gesto de apagar é intenção explícita de remover a pessoa inteira. (assumido — validar no gate)
  • Carteira e conta de acesso do apagado: remover automaticamente dos municipality.advisors / activity.advisors e apagar a conta campaignUser vinculada (cascata existente de passkeys/notificações)? Recomendação: sim, na mesma transação, declarado no diálogo. (assumido — validar no gate)

Referências

  • pessoas-identidade-contact.md (C99, pré-requisito)
  • B18 (filtros salvos), B127/B128 (omnibox), B159 (colunas de relação), B91 (busca global), docs/plans/sistema-listas-campanha.md (shells Pass 2 W1)
  • docs/plans/convite-whatsapp-lista-liderancas.md + LeadershipInviteRowAction (convite de cadastro por linha — fluxo a reusar)
  • Precedente de cascata e LGPD: removeSupporterData (anônima Contact quando sem outros joins) e hooks beforeDelete de campaignUser (passkeys/notificações)
  • Canvas UI (gate): plan-c100-ui-draft.canvas.tsx
  • AGENTS.md — modelo Municípios, leader lockdown, naming pt-BR em labels