10 KiB
Coluna de lideranças na tabela de municípios
Status: rascunho
Atualizado em: 2026-08-04
Issue: #359
Priority: P2
Model: composer-2.5
Impeccable: B — encaixe em MunicipalityList (/campanha/municipios), coluna nova ao lado de Assessores; sem rota nova de UI
Canvas UI: N/A — sem UI (o canvas da skill canvas não está disponível; a intenção visual é um espelho da coluna "Assessores" já existente — chips + Popover + Command, mesma máquina de interação)
Appetite: ~0,5–1 dia eng; uma coluna editável na tabela de municípios
Responsável: —
Intenção
Hoje, na tabela de municípios (/campanha/municipios), a equipe de campanha vê e edita os assessores designados inline (coluna "Assessores"). Mas as lideranças vinculadas a cada município só são visíveis entrando na ficha individual da liderança — não há uma coluna que mostre "quais lideranças atuam neste município" na lista. Isso obriga a navegar para a lista de lideranças (/campanha/liderancas) ou abrir o detalhe do município para cruzar essa informação.
O pedido é espelhar a coluna "Assessores" com uma coluna "Lideranças": mesma affordance de edição inline (chips + typeahead + criar inline), mesma máquina de interação, mesma visibilidade por papel.
Persona e fluxo
- Persona / contexto: Staff da campanha (coordenação, assessores) na mesa de operações, navegando a lista de municípios para decidir alocação, priorização e próximos passos.
- Job principal: Ver e editar quais lideranças estão vinculadas a cada município — diretamente na lista, sem sair da tabela.
- Fluxo desejado:
- Staff abre
/campanha/municipiose vê a coluna "Lideranças" ao lado de "Assessores". - Cada célula mostra chips com os nomes das lideranças vinculadas ao município (ou "Nenhuma" se vazio).
- Staff clica na célula → abre Popover com typeahead (busca por nome do contato) + lista de chips removíveis.
- Staff digita para buscar uma liderança existente → seleciona → chip aparece otimista (antes do servidor confirmar).
- Se a liderança não existe ainda, staff pode criar inline (abre mini-form com nome do contato + telefone; cria no servidor como nova
leadershipvinculada a este município; erro faz rollback). - Staff remove um chip → ele some otimista. Se o servidor falhar, volta + toast de erro.
- Lideranças adicionadas/removidas inline são refletidas imediatamente na lista (sem recarregar a página).
- Staff abre
- Anti-goals de produto:
- Não é um formulário multi-campo de edição de liderança (status, exclusividade, organizações, dobradinhas) — isso continua na ficha
/campanha/liderancas/[id]. - Não é uma segunda lista de lideranças embutida na tabela de municípios — é uma coluna de vínculo rápido, igual a de assessores.
- Líder (papel
leader) não vê esta coluna — lockdown permanece.
- Não é um formulário multi-campo de edição de liderança (status, exclusividade, organizações, dobradinhas) — isso continua na ficha
Esboço de fluxo
Lista de municípios (staff)
│
├─ Coluna "Lideranças"
│ ├─ Célula fechada: chips com nome da liderança (ou "Nenhuma")
│ └─ Célula aberta (Popover):
│ ├─ Typeahead (Command): busca por nome do contato
│ ├─ Chips removíveis: cada liderança vinculada
│ └─ "Criar liderança" inline (se não encontrada na busca)
│ └─ Mini-form: nome + telefone → cria → vincula
│
└─ Mutação otimista + rollback em erro (mesmo padrão de assessores)
Objetivo e aceite
- Coluna "Lideranças" aparece na tabela de municípios para staff (coordenação + assessores), ao lado ou próxima da coluna "Assessores".
- Célula mostra chips com o nome do contato de cada liderança vinculada ao município. Município sem lideranças mostra "Nenhuma" (ou badge equivalente ao
MissingAdvisorBadgequando prioritário). - Staff pode adicionar/remover lideranças inline: typeahead busca por nome do contato (via
contact.name), seleção otimista, rollback em erro de rede/servidor. - Staff pode criar uma nova liderança inline vinculada ao município atual, sem sair da tabela.
- Assessor só vê e edita lideranças dos municípios que administra (mesmo escopo de
canReadLeadership+ filtroadvisors). - Coordenação e candidato veem e editam todas.
- Líder (
leader) não vê a coluna (lockdown). - Guardrails: sem migration fora do padrão, sem collection nova, sem alterar o schema de
leadership;Consentpermanece fail-closed para lideranças novas criadas inline (mesmo comportamento de criar liderança pelo form completo).
Dados (intenção)
- Vou apresentar dados? Não — coluna qualitativa de vínculo. Sem métrica, contagem, série ou ranking.
- Decisões desbloqueadas: Staff decide "quem está conosco neste município" diretamente na lista, sem abrir ficha externa.
- Forma: adiada ao plano de implementação — chips com nome do contato, igual a assessores.
Direção no codebase (hipótese)
- Áreas prováveis:
src/collections/Municipality.ts— novo fieldleadership(relationship →leadership,hasMany), mirror deadvisors(linhas 298–310)src/components/campaign/municipality/MunicipalityList.tsx— nova colunaleadershipsna definição demunicipalityListColumnssrc/components/campaign/municipality/MunicipalityListLeadershipsControl.tsx— novo componente (espelho deMunicipalityListAdvisorsControl.tsx)src/app/(campaign)/campanha/(app)/municipios/leaderships/route.ts+types.ts— endpoint JSON de mutação (espelho deadvisors/)src/utilities/municipality/municipalityViewModels.ts— estenderMunicipalityListViewModelcomleadershipIDseLeadershipSummarysrc/utilities/access/municipalities.ts— funções de access (espelho decanAssignMunicipalityAdvisors/canManageMunicipalityAdvisors)src/utilities/access/leaderships.ts— já existecanReadLeadership; verificar se precisa decanManageLeadershipMembership
- Precedente a olhar:
MunicipalityListAdvisorsControl.tsx— a máquina completa de interação (chips + Popover + Command + delta otimista + undo + aria-live)src/app/(campaign)/campanha/(app)/municipios/advisors/route.ts— contrato do endpoint JSON- B154 (
docs/plans/criar-assessor-inline-municipio.mdse existir) — criar inline no popover src/utilities/municipality/municipalityViewModels.ts—EligibleAdvisorOption,MunicipalityAdvisorSummarycomo padrão paraEligibleLeadershipOption,MunicipalityLeadershipSummaryRelationChipCellgenérico (src/components/campaign/shared/RelationChipCell.tsx) — se já cobre o caso de relação many-to-many com typeahead + undo, o controle de lideranças pode ser um wrapper fino em vez de duplicar a máquina
- Risco de acoplamento:
- Leader lockdown:
isCampaignStaff/isCoordinatorjá controlam a visibilidade da coluna de assessores; a de lideranças deve usar o mesmo gate. - Relação bidirecional:
leadership.municipalitiesemunicipality.leadershipsprecisam manter consistência — adicionar uma liderança ao município deve ser visível na lista de lideranças também. - Migração: o novo field
leadershipnoMunicipalityprecisa de uma migration; se houver lideranças já vinculadas (vialeadership.municipalities), a migration de reconciliação deve popularmunicipality.leadershipsa partir dos dados existentes para não quebrar a relação reversa.
- Leader lockdown:
Dependências
- Nenhuma (item auto-contido)
Fora de escopo
- Editar campos da liderança (status, exclusividade, organizações, dobradinhas) inline — isso continua na ficha
/campanha/liderancas/[id]. - Coluna de lideranças em outras listas (dobradinhas, organizações) — só a tabela de municípios neste item.
- Criar contato (
Contact) inline — criar uma liderança inline exige umContactexistente ou a criação de um novoContactno mesmo fluxo (a decidir na implementação; se o mini-form inline criarContact+Leadershipem transação, é aceitável e segue o padrão de criar assessor do B154).
Rabbit holes de produto
- Sincronia bidirecional
leadership.municipalities↔municipality.leaderships. Se alguém "só adicionar o campo no Payload", as duas pontas da relação divergem (editar a liderança via/liderancas/[id]não atualizamunicipality.leaderships, e vice-versa). Corte neste item: definir UMA ponta canônica de escrita (provável:municipality.leadershipscomo source of truth, com hook que sincronizaleadership.municipalities; ou manterleadership.municipalitiescomo canônica e a coluna do município ser só leitura/atalho). A decisão é de implementação, mas o plano de intenção registra o risco. - Performance com muitas lideranças. Um município pode ter dezenas de lideranças; carregar todos os nomes para todas as 435 linhas da tabela pode ser pesado. Corte neste item: seguir o mesmo padrão de assessores (batch de names por ID, carregado uma vez no server component). Se for lento, paginar ou virtualizar — mas não neste item.
Questões em aberto (produto)
A coluna substitui ou complementa a seção de lideranças no detalhe do município (B152)?Resolvido: A — a coluna é atalho de edição rápida; o detalhe do município continua mostrando lideranças com mais informação.Criar liderança inline exige criarResolvido: B — mini-form criaContactjunto?Contact+Leadershipno mesmo passo (igual B154).A coluna deve aparecer antes ou depois de "Assessores"?Resolvido: depois de "Assessores".Sincronia bidirecionalResolvido: relação verdadeiramente bidirecional — editar a coluna do município atualizaleadership.municipalities↔municipality.leaderships?leadership.municipalitiestambém.
Referências
src/collections/Municipality.ts— fieldadvisors(L298–310): padrão a espelharsrc/components/campaign/municipality/MunicipalityListAdvisorsControl.tsx— máquina de interação completasrc/app/(campaign)/campanha/(app)/municipios/advisors/route.ts— contrato do endpoint JSONsrc/components/campaign/shared/RelationChipCell.tsx— se aplicável como wrapper genéricosrc/collections/Leadership.ts— coleção de lideranças, fieldmunicipalities(relação reversa)AGENTS.md— "Campaign Municípios model", "Campaign auth" (lockdown de líder)