Replace all project-local .cursor/ path references with .agents/ across rules, skills, environment config, hooks, and ignore files. Keep Cursor editor paths (~/.cursor/, window.cursor, CURSOR_API_KEY) and vendored Impeccable editor-hook paths unchanged.
25 KiB
Chips de lideranças na lista de dobradinhas (espelho da coluna Municípios de Assessores)
Status: entregue (2026-07-26)
Atualizado em: 2026-07-26
Item do roadmap: docs/roadmap.md (Trilha B, item B36 ✓)
Impeccable: B — encaixe na coluna "Lideranças" de /campanha/dobradinhas, reusando o padrão visual já em produção em /campanha/assessores (B19 ✓) e a mutação entregue pelo B31 ✓ para o lado inverso da mesma relação
Appetite: ~0,75–1d (B31 já aterrissado; paga a extração da célula compartilhada que o B31 deixou pendente)
Responsável: —
Revisão na entrega (2026-07-26)
Auditoria pré-implementação contra o B31 as-built:
- Context → columns factory. O plano pedia
RelationOptionsProvider; o B31/simplifyrodada 2 já tinha deletado o Context em favor deleadershipColumns(options). Entrega seguiu o precedente:stateDeputyColumns(..., leadershipOptions)+toLeadershipRelationOptions. - Casca por rota.
setLeadershipStateDeputyMembershipFormActionganhou cópia fina emdobradinhas/formActions.ts(não importa deliderancas/—formActionssão cascas por rota no codebase-map). Mutação/schema/lock inalterados. - Célula compartilhada.
LeadershipStateDeputiesCelldeletado; nasceshared/LeadershipStateDeputyRelationCellcomdirection+measureOverflow(default true; lado liderança passafalse). Tipos de UI:RelationCellItem/RelationCellOption. - Loader.
leadershipCount→leaderships: {id,name}[]emStateDeputyRowViewModel;loadLeadershipOptionsemcampaignRelationOptions.ts.
As-built bate com as Decisões travadas de mutação/reuso; só o packaging de UI/catalogo divergiu do rascunho de 25/07, alinhado ao B31 real.
Design (Impeccable)
Âncoras: PRODUCT.md (princípios 3 Edit where you see, 4 Auto-save, no Save button, 8 Feel the action; anti-goals "spreadsheet mode" e "always-mounted inputs on every row") / DESIGN.md (register product; Field Desk) · tema data-theme='campaign' · precedentes de interação AdvisorMunicipalityCell.tsx (B19 ✓ — chips removíveis + typeahead + otimista + ResizeObserver/"Ver mais…") e o desenho ainda não implementado do B31 (dobradinhas-lista-liderancas.md — chips + Popover + Command, sem "Ver mais…", para a mesma relação leadership.stateDeputies na direção oposta) · shells CampaignTable / CampaignPageShell · regras .agents/rules/campanha-edit-where-you-see.mdc e campanha-action-feedback.mdc.
Na implementação (implement-roadmap-item): craft compacto (a maior parte da interação já foi decidida no B31; craft aqui é sobretudo a direção nova + o clamp de overflow) → critique → polish. harden/optimize só sob gatilho do Passo 8.
Brief compacto:
- Persona / contexto: CG / Assessor olhando
/campanha/dobradinhase querendo ver, de um deputado estadual, quais lideranças já estão amarradas a ele — e corrigir isso sem abrir uma ficha de liderança por vez. É o mesmo job do B31, visto do lado do deputado em vez do lado da liderança. - Job principal: ver e editar as lideranças de uma dobradinha direto na tabela, com o mesmo gesto com que já se edita a carteira de município de um assessor.
- Estratégia de cor: Restrained — chips
Badge variant="secondary", sem paleta nova. - Edit where you see: sim — mesma affordance do B31/Assessores (chips removíveis, busca inline, sem toggle de tabela inteira); o pedido do usuário nomeia explicitamente "não duplicar lógica" — a resposta de design é reusar a mesma mutação e a mesma forma de célula, não inventar uma segunda.
- Anti-goals: modo "Editar" de tabela inteira; segundo componente de célula fazendo a mesma coisa que o do B31 com um nome diferente; agrupamento por município/TI nos chips (essa relação não tem hierarquia territorial).
Dados → decisão → apresentação
- Vou apresentar dados? Sim — a mesma relação categórica
leadership.stateDeputies, vista do lado dostateDeputy. Hoje a lista de dobradinhas descarta o detalhe e mostra sóleadershipCount: number. - Decisões desbloqueadas:
- Coordenador/Assessor olhando a ficha de um deputado: "quais lideranças já estão de fato amarradas a ele — e há alguma faltando?" (mesmo flanco de fogo amigo intra-campo nomeado em CUSTOMER.md).
- Coordenador fazendo triagem por deputado (em vez de por liderança, como o B31 já resolve): completar em lote as fichas de um deputado específico, útil quando o dado chega organizado "por candidato" em vez de "por pessoa" (o caso comum de planilha de campanha).
- Forma escolhida: tabela/lista — coluna com chips nomeados (link para
/campanha/liderancas/[id]), igual ao tratamento já decidido para "Municípios"/"Organizações" e ao que o B31 decidiu para "Dobradinhas" na tabela de lideranças. Rejeitado: manter a contagem (esconde o nome, que é a decisão); qualquer chart/mapa (dado nominal/categórico, "quem" não "onde"/"quanto"). - Profile: categórico; granularidade
stateDeputy×leadership; tamanho potencialmente maior por linha do que no B31 — um deputado popular pode acumular dezenas de lideranças engajadas, enquanto uma liderança tipicamente dobra com 0–2 deputados. Essa assimetria é a razão de design central deste item (ver Decisões travadas #3). - Anti-goals de dado: sem métrica eleitoral derivada; sem ranking de deputados por número de lideranças; sem inferir a partir de
municipality.stateDeputies(união automática misturaria vínculo sabido com suposto, mesmo anti-goal do B31).
Self-check dados: 5/5.
Contexto
/campanha/dobradinhas (page.tsx) lista deputados estaduais com colunas Nome · Partido · Municípios · Lideranças. As duas últimas são só contagens (municipalityCount/leadershipCount) calculadas em stateDeputyData.ts por uma query batch em leadership/municipality filtrada por stateDeputies: { in: stateDeputyIDs } } — a mesma forma de agregação que a ficha loadStateDeputyDetail já usa para resolver nomes (não só contagem) de município e liderança, só que ali para um único deputado.
O usuário pediu explicitamente que a coluna "Lideranças" ganhe "as mesmas funcionalidades e UI" da coluna "Municípios" de /campanha/assessores (B19 ✓ — chips clicáveis, chips removíveis + busca no modo edição, gravação por delta com estado otimista, "Ver mais…" quando a carteira não cabe em 3 linhas) — e pediu para não duplicar lógica, reutilizando funções e componentes.
Isso importa porque existe hoje, em plano (ainda não implementado), o item B31 (dobradinhas-lista-liderancas.md) resolvendo exatamente a mesma relação leadership.stateDeputies, só que a partir da tabela de lideranças: lá, cada linha é uma liderança fixa e os chips são as dobradinhas dela; aqui, cada linha é uma dobradinha fixa e os chips são as lideranças dela. É a mesma aresta de grafo, editada dos dois lados — exatamente o cenário em que "reusar, não duplicar" tem uma resposta concreta: a mutação (ler o array leadership.stateDeputies, aplicar um toggle, escrever) é idêntica nas duas direções, porque o campo relacional só existe do lado da leadership. O que muda é qual id fica fixo e qual vem da busca — e a UI da célula (chips + Popover + Command + otimista) também é idêntica na forma, mudando só a lista de origem/destino e o link do chip.
Objetivos
- Coluna "Lideranças" em
/campanha/dobradinhastroca a contagem morta por chips nomeados, cada um linkando para/campanha/liderancas/[id]. - Adicionar/remover liderança na própria linha, com busca acento-insensível por nome sobre o catálogo de lideranças acessíveis ao ator, sem botão "Salvar": grava por delta, com chip otimista, erro revertido + toast.
- Clamp de 3 linhas + "Ver mais…" (mesma medição por
ResizeObserverdoAdvisorMunicipalityCell) — necessário aqui porque, ao contrário do B31, o volume de chips por linha pode crescer bastante (ver Decisões travadas #3). - Zero segunda implementação da mutação ou da mecânica de célula: reutiliza a action/schema/lock que o B31 introduz para a mesma relação, e um único componente de célula cobre as duas direções (B31 e este item).
StateDeputyRowViewModel.leadershipCounté substituído porleaderships: LeadershipRelationSummary[](id + nome), resolvido pela mesma query batch já existente (mais umdepth/select, não uma segunda consulta).- Guardrails: sem migration, sem collection, sem Consent, sem mudança de contrato de URL da lista; access reaproveitado (a leitura/escrita de
leadershipcomoverrideAccess: falsejá resolve o escopo do assessor);leadercontinua fora da rota (isCampaignStaffjá exclui).
Decisões travadas
- Reusar literalmente a mutação do B31, sem um segundo caminho de código. A relação mora só em
leadership.stateDeputies; "editar do lado do deputado" continua sendo ler-modificar-escrever o documento daleadership, só que comleadershipIdvariável (escolhido na busca) estateDeputyIdfixo (o da linha) — o espelho exato de como o B31 chama a mesma função comstateDeputyIdvariável eleadershipIdfixo. Este item não introduz uma action nova: usasetLeadershipStateDeputyMembershipRecord/setLeadershipStateDeputyMembership(schemaleadershipStateDeputyMembershipSchema, lockleadership-state-deputies:{id}) exatamente como o B31 os deixar. Por quê: é a definição operacional do pedido "não duplicar lógica" — a mesma checagem de escopo, o mesmo lock, o mesmo teto (MAX_LEADERSHIP_STATE_DEPUTIES, 20) e a mesma transação já resolvem os dois sentidos. Rejeitado: uma action "do lado dostateDeputy" espelhando a lógica — duplicaria exatamente a leitura-modificação-escrita que o B31 já resolve; um endpoint JSON dedicado só para esta direção — mesmo raciocínio, sem ganho. - Um único componente de célula bidirecional para a mesma aresta, não dois componentes que fazem a mesma coisa com nomes diferentes.
LeadershipStateDeputyRelationCell(client, emsrc/components/campaign/shared/) recebedirection: 'fromStateDeputy' | 'fromLeadership', o id da linha fixa, os itens já vinculados ({id, name, href}[]) e o catálogo de opções do outro lado (já filtrado/rotulado pelo chamador). O B31 monta essa célula comdirection: 'fromLeadership'(chips = dobradinhas, catálogo =loadStateDeputyOptions); este item monta comdirection: 'fromStateDeputy'(chips = lideranças, catálogo =loadLeadershipOptions, novo). Por quê: as duas montagens compartilham 100% da mecânica (Popover,Command,matchesAtWordStart,useTransition, estado otimista, reversão em erro, toast) — só o rótulo dos chips, o link e qual lado da tupla{leadershipId, stateDeputyId}é fixo mudam. Rejeitado: um componenteStateDeputyLeadershipsCellpróprio deste item, irmão gêmeo doLeadershipStateDeputiesCelldo B31 — é exatamente a "segunda cópia da mesma lógica" que o pedido do usuário proíbe; um editor genéricoRelationshipChipEditoragnóstico de qual relação edita — prematuro (só existe uma relação com esta forma até aqui; a de municípios tem agrupamento por TI/ZE, é outra forma — ver Adiado com gatilho). - Incluir o clamp de 3 linhas + "Ver mais…" (portado do
AdvisorMunicipalityCell) no componente compartilhado, atrás de um prop opcional (measureOverflow, defaulttrue). O B31 decidiu não portar essa medição para a direção "de liderança" porque uma liderança tipicamente dobra com 0–2 deputados (poucos chips, sem estouro). Este item pede exatamente a paridade com Assessores — cujo motivo de existir é uma carteira que pode crescer além de 3 linhas — e aqui a assimetria é real: um deputado popular pode acumular dezenas de lideranças engajadas. Por quê: ligar/desligar por prop custa uma linha de código no componente compartilhado; não portar deixaria a linha de um deputado popular crescer sem limite ao lado de Nome/Partido/Municípios, quebrando a densidade da própria lista que este item está tentando tornar legível. Rejeitado: sem clamp em nenhuma direção (whitespace-normal) — reproduziria em/campanha/dobradinhaso mesmo problema que motivou o "Ver mais…" em Assessores; clamp obrigatório sempre — گasto deResizeObserversem necessidade real no lado "de liderança", que o B31 já mediu como raro. - Catálogo de busca (
loadLeadershipOptions, novo emcampaignRelationOptions.ts) viapayload.find({ collection: 'leadership', user, overrideAccess: false }), sem interseção manual comgetAccessibleLeadershipIds. Por quê: é o mesmo padrão que já sustentaloadStateDeputyOptions/loadMunicipalityOptions/loadOrganizationOptions— o access de linha decanReadLeadershipjá resolve o escopo do assessor no própriofind; a autoridade real de qualquer forma está na mutação (overrideAccess: falseno read-modify-write), então escopar a busca de novo seria replicar uma regra que o Payload já aplica. Rejeitado: buscar todas as lideranças comoverrideAccess: truee filtrar em memória — reintroduz manualmente uma regra de acesso que já existe. stateDeputyData.ts: a query batch deleadership(já filtrada porstateDeputies: { in: stateDeputyIDs } }) ganhadepth: 1+select: { stateDeputies: true, contact: true }e passa a agrupar{id, name}por deputado, no lugar da contagem — mesma forma queloadStateDeputyDetailjá usa para a ficha, promovida para a query em lote da lista.StateDeputyRowViewModel.leadershipCounté substituído porleaderships: LeadershipRelationSummary[]. Por quê: é uma extensão de campos (select) na mesma query já existente, não uma segunda consulta — literalmente a definição de "não duplicar lógica" aplicada ao loader. Rejeitado: manterleadershipCounte adicionar uma segunda query de nomes sobre o mesmowhere— dois round-trips ao banco para o mesmo filtro é a duplicação que o pedido nomeia.- i18n e naming seguem o AGENTS.md: identificadores em inglês (
LeadershipStateDeputyRelationCell,loadLeadershipOptions,LeadershipRelationSummary), strings visíveis em pt-BR ("Lideranças", "Adicionar liderança…", "Ver mais…").
Questões em aberto
- O componente compartilhado (
LeadershipStateDeputyRelationCell) mora emshared/ou emstateDeputy/? Opções: A)src/components/campaign/shared/— é consumido por duas rotas de dois domínios diferentes (dobradinhas/page.tsxeliderancas/page.tsx) | B)src/components/campaign/stateDeputy/, importado cross-domínio pela rota de lideranças. Recomendação: A —codebase-map.mdcjá reservashared/para o que mais de um domínio consome (precedente:CampaignTable,CampaignListFooter); manter emstateDeputy/obrigarialiderancas/a importar de outro domínio, o acoplamento que o mapa de código proíbe. - Este item entra na mesma entrega do B31, ou depois, consumindo o que o B31 já tiver extraído? Opções: A) mesma PR/sessão — constrói a célula e a action uma vez, já cobrindo as duas direções | B) B36 entra depois do B31 (padrão de corrida já usado em B21/B29/B33: quem chega primeiro paga a peça compartilhada, o outro só consome). Recomendação: B — mantém cada entrega revisável e no appetite calculado acima; se produto preferir as duas juntas, o appetite combinado (~1,5–2 dias) cobre.
- Existe algum teto simétrico do lado do
stateDeputy(limite de lideranças por deputado)? Opções: A) nenhum teto novo — o teto de 20 lideranças por dobradinha (MAX_LEADERSHIP_STATE_DEPUTIES, do lado daleadership) já limita o fan-out sem necessidade de um segundo campo | B) adicionar teto simétrico. Recomendação: A — sem evidência de necessidade; o clamp visual (item de design acima) já resolve a legibilidade da célula independente de quantos chips existem de fato.
Abordagem proposta
flowchart LR
loader["loadStateDeputyListPageData<br/>+ leaderships (id/nome, mesma query batch)"] --> page["dobradinhas/page.tsx<br/>coluna Lideranças"]
options["loadLeadershipOptions<br/>(novo, overrideAccess: false)"] --> provider["RelationOptionsProvider<leadership><br/>(1× por tabela)"]
provider --> cell["LeadershipStateDeputyRelationCell<br/>direction='fromStateDeputy'"]
page --> cell
cell -->|delta assigned| action["setLeadershipStateDeputyMembership<br/>(do B31 — reusada sem alteração)"]
action --> revalidate["revalidatePath<br/>dobradinhas · liderancas (mesmas 4 rotas do B31)"]
Componentes:
src/components/campaign/shared/LeadershipStateDeputyRelationCell.tsx(novo — se o B31 já tiver entregue seuLeadershipStateDeputiesCell, este item promove/renomeia aquele componente parashared/e adicionadirection/measureOverflowem vez de criar um arquivo paralelo). Props:direction: 'fromStateDeputy' | 'fromLeadership',fixedId: number,items: { id: number; name: string; href: string }[],options: RelationOption[],measureOverflow?: boolean(defaulttrue),disabled?: boolean. Internamente: chips (Badge+Link) no repouso; Popover com chips removíveis +Command(busca viamatchesAtWordStart) para adicionar;useTransition+ estado otimista +toast.errorcom reversão; quandomeasureOverflow, o mesmoResizeObserverde 3 linhas + "Ver mais…" doAdvisorMunicipalityCell.src/components/campaign/shared/RelationOptionsProvider.tsx(novo, genérico só na forma — não na relação):Context<RelationOption[]>+useRelationOptions(); monta uma vez em volta doCampaignTable. Reusado pelo B31 (catálogo de dobradinhas) e por este item (catálogo de lideranças) — mesmo formato (RelationOption[]), dois consumidores reais, sem parametrizar nada específico de domínio.src/utilities/campaignRelationOptions.ts:loadLeadershipOptions(payload, user)(novo) — espelhaloadStateDeputyOptions:payload.find({ collection: 'leadership', depth: 1, select: { contact: true }, user, overrideAccess: false }), mapeando para{ id, name: contact.name }.src/utilities/stateDeputyData.ts:StateDeputyRowViewModel.leadershipCount→leaderships: LeadershipRelationSummary[]({id, name}); a query batch deleadershipemloadStateDeputyListPageDataganhadepth: 1eselect: { stateDeputies: true, contact: true }, agrupando por deputado no lugar de só contar.LeadershipRelationSummaryexportado para o componente da célula construirhref/label.src/app/(campaign)/campanha/(app)/dobradinhas/page.tsx: a colunaleadershipspassa a renderizar<LeadershipStateDeputyRelationCell direction="fromStateDeputy" fixedId={row.id} items={row.leaderships.map(l => ({...l, href: \/campanha/liderancas/${l.id}`}))} .../>; a página carregaloadLeadershipOptions(payload, user)no mesmoPromise.alldo loader da lista e envolve a tabela em`.- Sem migration, sem collection, sem action nova, sem endpoint JSON, sem schema novo — reusa integralmente
setLeadershipStateDeputyMembership/leadershipStateDeputyMembershipSchema/lock do B31. - Testes: estende os testes de
nextStateDeputyIdsAfterMembership/action do B31 com um caso de invocação "pelo lado do deputado" (mesmo resultado, ids trocados); teste deloadLeadershipOptionsrespeitando escopo do assessor; teste do loader destateDeputyData.tsconfirmandoleaderships(não maisleadershipCount) no row.
Depth check: reusa CampaignTable, Popover/Command/Badge do kit, wordStartFilter, a action/schema/lock do B31, campaignAccess. Não introduz um segundo caminho de mutação nem um segundo componente de célula — o ponto central do pedido.
Dependências
- Soft, corrida com B31 (
docs/plans/dobradinhas-lista-liderancas.md): quem entrar primeiro paga a extração deLeadershipStateDeputyRelationCell(a partir doLeadershipStateDeputiesCellque o B31 desenha) +RelationOptionsProvider+ a action/schema/lock; o outro consome sem alterar. Mesmo padrão de corrida já documentado para B21/B29/B33. - Soft: B19 ✓ (padrão de interação de origem,
AdvisorMunicipalityCell), E4R ✓ (criou o catálogo de dobradinhas e deixou as fichas de liderança vazias — é o motivo de haver trabalho de preenchimento em lote dos dois lados), B33 (mesma tabela — se o header de sort/filtro de dobradinhas entrar primeiro, esta coluna nasce sob o header rico; se entrar depois, herda). - Reusa sem alterar:
withPayloadTransaction,acquireTextAdvisoryLocks,canManageLeadership/canReadLeadership(src/utilities/access/leaderships.ts),canReadStateDeputy(src/utilities/access/stateDeputies.ts),runCampaignFormAction. - Nenhuma dependência dura de outro item aberto do roadmap.
Não escopo
- Agrupamento de chips por município/Território de Identidade (a metade "lote" do widget de Assessores) — a relação dobradinha↔liderança não tem hierarquia territorial análoga; mesma decisão do B31 para a direção espelhada.
- Filtro/ordenação por lideranças no header de
/campanha/dobradinhas— o B33 cobre apenas Nome/Partido; vira gatilho registrado ali se a mesa pedir. - Editar a coluna "Municípios" de
/campanha/dobradinhaspelo mesmo padrão — vínculo indireto viamunicipality.stateDeputies(outra collection, outro dono de escrita), fora do pedido. - Criar liderança nova a partir da célula ("adicionar e cadastrar") —
/campanha/liderancas/novacontinua sendo o caminho. - Generalizar
LeadershipStateDeputyRelationCell/RelationOptionsProviderpara qualquer relação (municípios, organizações) — ver Adiado com gatilho.
Rabbit holes
- Generalizar demais enquanto o arquivo já está aberto. É tentador, ao extrair a célula para
shared/, torná-la um editor de relação totalmente agnóstico (qualquer collection, qualquer campo). Mitigação: parar emLeadershipStateDeputyRelationCell, escopado literalmente à arestaleadership.stateDeputies; a de municípios (MunicipalityPortfolioCell, do planochips-municipios-lista-liderancas.md) tem agrupamento TI/ZE — é uma forma diferente, não o mesmo componente com um nome trocado. - Migrar consumidores de
leadershipCountsem verificar quem mais lê esse campo. Antes de removerleadershipCountdeStateDeputyRowViewModel,git grep -w leadershipCount— se algum outro lugar (painel/overview) só precisa do número,row.leaderships.lengthsubstitui sem tocar naquele markup fora do escopo deste item. - Ajustar o clamp de 3 linhas do B31 "por tabela ter mudado" quando na verdade o volume só mudou no lado do deputado. O prop
measureOverflowexiste exatamente para isolar essa decisão por direção; não elevar/reduzir o limiar do lado "de liderança" sem evidência nova.
Adiado com gatilho
- Editor de relação totalmente genérico (
RelationshipChipEditor), incluindo municípios/organizações. Revisitar quando uma 3ª relação sem agrupamento territorial pedir exatamente esta forma (mesmo gatilho já registrado no B31). - Busca de liderança no servidor em vez de catálogo client-side completo. Revisitar quando o catálogo de lideranças passar de ~200 registros (mesmo gatilho/métrica do B31).
- Teto simétrico de lideranças por dobradinha. Revisitar só com evidência real de um deputado acumulando um volume que quebre a legibilidade mesmo com o clamp.
Referências
docs/roadmap.md(Trilha B — item B36, ao lado de B31/B33)dobradinhas-lista-liderancas.md(B31) — desenho da mutação/ação/lock/schema que este item reusa sem alteração, e da célula que este item promove parashared/gerenciar-assessores.md(B19 ✓) — origem do padrão de chips + busca + otimista + "Ver mais…"src/app/(campaign)/campanha/(app)/dobradinhas/page.tsx,src/utilities/stateDeputyData.ts— superfície e view model a estendersrc/components/campaign/advisor/AdvisorMunicipalityCell.tsx— origem do clamp de 3 linhas +ResizeObserver/"Ver mais…" a portarsrc/utilities/campaignRelationOptions.ts(loadStateDeputyOptions,loadMunicipalityOptions) — padrão a espelhar emloadLeadershipOptionssrc/utilities/access/leaderships.ts(canReadLeadership,canManageLeadership) — access que a leitura/escrita reusa sem alterarsrc/lib/wordStartFilter.ts(matchesAtWordStart,normalizeSearchPhrase) — busca acento-insensível reusada- AGENTS.md — Campaign Municípios model, Transaction Safety, naming em inglês/copy em pt-BR
.agents/rules/campanha-edit-where-you-see.mdc,.agents/rules/campanha-action-feedback.mdc— princípios de UX herdados de Assessores/B31