Espelho da coluna de Assessores: chips com nome do contato, popover/sheet com Command + delta otimista e criação inline (Nome + Celular). Sem migration — leitura reversa de leadership.municipalities no bundle e escrita reusando as actions B34/wizard; rota POST /campanha/municipios/leaderships via campaignJsonMutationRoute.
12 KiB
Impl: Coluna de lideranças na tabela de municípios
Status: aprovado Atualizado em: 2026-08-04 Issue: #359 Intenção: docs/plans/liderancas-coluna-municipios.md Appetite restante: herdado (~0,5–1 dia eng)
Leitura da intenção
- Outcome: staff vê e edita, direto na lista
/campanha/municipios, as lideranças vinculadas a cada município — chips com nome do contato, popover com busca, adição/remoção com auto-save otimista, e criação inline (nome + telefone) sem sair da tabela. Coluna ao lado de "Assessores". - O que NÃO negociar: líder (
leader) não vê a coluna (nem acessa a página —gate: noLeaderjá cobre); assessor só vê/edita lideranças dos municípios que administra (canReadLeadership+assertMunicipalitiesWithinScope); sem collection nova; sem migration fora do padrão;Consentpermanece fail-closed (a criação inline reusacreateValidatedLeadershipRecord, que não introduz chave nova — mesmo comportamento do form completo). - O que reavaliar: a hipótese da intenção ("novo field
leadershipnoMunicipality, mirror deadvisors", com migração de reconciliação) é rejeitada neste impl plan. A relação canônica já existe (leadership.municipalities) e o B34 já escreve esse lado. Ler por query reversa + reusar as actions B34/B154 elimina migration, join table nova e sync bidirecional.
Abordagem recomendada
flowchart LR
A["page.tsx /campanha/municipios"] --> B["loadMunicipalityListPageBundle"]
B --> C["query reversa (staff): leaderships<br/>municipalities in pageIDs, depth 1"]
C --> D["rows ganham leadershipIDs<br/>+ retorna leadershipNamesById"]
A --> E["getEligibleLeadershipOptions (staff)"]
D --> F["MunicipalityList — coluna Lideranças"]
E --> F
F --> G["MunicipalityListLeadershipsControl<br/>(popover desktop / sheet mobile)"]
G --> I["POST /campanha/municipios/leaderships"]
I --> J["toggle → setLeadershipMunicipalitiesMembership (B34, reuso)"]
I --> K["create → createMunicipalityLeadership (wrapper fino<br/>→ createLeadershipWizardRecord existente)"]
Opções consideradas: A | B | C
Recomendação: B — leitura reversa de leadership.municipalities + reuso das actions B34/B154/wizard. Zero migration, fonte única de verdade (uma ponta canônica), consistência automática com a coluna "Municípios" de /campanha/liderancas (B34) e com a ficha da liderança — sem hooks de sync que possam divergir. Depth check: reusa actions, schemas, CampaignCellEditOverlay, padrão de provider do B154.
Rejeitadas:
- A — novo campo
municipality.leaderships(hasMany) + migration + migração de reconciliação + sync bidirecional comleadership.municipalitiespor hooks nas duas collections. Custo de reverter alto (join table nova numa collection "system" de 435 rows + hooks de sync que divergem silenciosamente — o classic footgun do Payload); não traz aceite adicional. - C — coluna read-only para assessor (só coordenação edita). Viola o aceite: "Assessor só vê e edita lideranças dos municípios que administra".
Componentes / mudanças
MunicipalityListColumnId(src/utilities/municipality/municipalityLabels.ts): ganha'leaderships'(closed union).municipalityColumnDescriptionsganha entrada.municipalityColumnLabels(src/utilities/municipality/municipalityListUrl.ts):leaderships: 'Lideranças'.MunicipalityListViewModel(src/utilities/municipality/municipalityViewModels.ts): ganhaleadershipIDs: number[](default[], populado pelo bundle só na staff view). Novos tiposMunicipalityLeadershipSummary({ id, name }) eEligibleLeadershipOption({ id, name }), mais os helpersloadMunicipalityLeadershipSummaries(payload, user, municipalityIDs)(uma query reversa batch) egetEligibleLeadershipOptions(payload, user)(espelho degetEligibleAdvisorOptions; escopo viaoverrideAccess: false+ user).loadMunicipalityListPageBundle(src/utilities/municipality/municipalityPageData.ts): para staff, uma queryleadership where { municipalities: { in: pageIDs } }comdepth: 1(contact),user/overrideAccess: false→ injetaleadershipIDsnos rows e devolveleadershipNamesByIdno bundle.page.tsx((app)/municipios): staff carregagetEligibleLeadershipOptionse repassaleadershipNamesById+leadershipOptionsaoMunicipalityList.MunicipalityList.tsx+MunicipalityListMobileCards.tsx(+ pass-through de props emMunicipalityListMobileSection): coluna'leaderships'no bloco staff apósadvisors(semMunicipalitySortableHead— header default viacolumn.label; não ordena nem filtra). Picker: entrada emmunicipalityListPickerColumns. Célula = controle novo para todo staff (advisors também gerenciam); card mobile ganha a linha "Lideranças" comvariant="sheet". Envolve a lista no novo provider.MunicipalityListLeadershipsControl.tsx(novo, client): espelho deMunicipalityListAdvisorsControl— chips de nome (sort pt-BR), trigger comaria-labelpor extenso,CampaignCellEditOverlay(popover/sheet),Commandcom buscamatchesAtWordStart, delta otimista (seq/pending/revert/latestConfirmedRef),Alertde erro. Branch de criação (diferente do B154 que cria em um clique só porquenamebastava):CommandItem"+ Criar liderança" → mini-form inline (Nome pré-preenchido + Telefonetype="tel") → POST → chip otimista com temp id negativo → swap pelo id real. Chips de temp-create sem × (mesmo contrato do B154).MunicipalityLeadershipCreateProvider.tsx(novo, client): bridge de opções criadas inline para todo o surface (espelho deMunicipalityAdvisorCreateProvider; 2 call sites → mirror, não abstrair).src/app/(campaign)/campanha/(app)/municipios/leaderships/route.ts(+types.ts, novos):POSTviacampaignJsonMutationRoute, bodyz.union(toggle{ municipalityId, leadershipId, assigned }| create{ municipalityId, name, phone }). Resposta{ status: 'success', leadershipIDs, createdLeadership?: { id, name } }—leadershipIDs= ids das lideranças do município após o write (query reversa id-only,overrideAccess: true— o write acabou de ser access-checkado; precedente B34).src/app/(campaign)/campanha/actions/leadership.ts: toggle reusasetLeadershipMunicipalitiesMembershiptal qual (o B34 já revalida ficha da liderança + detalhe do município; a lista onde estamos NÃO é revalidada — o chip é otimista, mesmo contrato do B34). create: wrapper finocreateMunicipalityLeadership({ municipalityId, name, phone })→createLeadershipWizardRecord+ slug lookup + revalidate (/campanha/liderancaslista +/campanha/municipios/<slug>), espelhandocreateMunicipalityAdvisor.- Schemas / safe messages: union parseado no route (padrão advisors, zod inline); allowlist =
LEADERSHIP_MUNICIPALITY_FLOOR_MESSAGE,LEADERSHIP_MUNICIPALITY_CAP_MESSAGE,LEADERSHIP_MUNICIPALITY_SCOPE_MESSAGE,LEADERSHIP_STAFF_MESSAGE,LEADERSHIP_DUPLICATE_MESSAGE,CONTACT_PHONE_AMBIGUOUS_MESSAGE,BRAZILIAN_PHONE_INVALID_MESSAGE,POSTGRES_DEDUP_LOCK_MESSAGE— todas lançadas pelas actions reusadas. - Migration: nenhuma.
Dados → forma
- Forma escolhida: chips de nome do contato na célula (espelho de assessores; sem avatar — liderança não tem
usernecessariamente). Popover: chips + Command. Vazio: "Nenhuma" (texto muted) — oMissingAdvisorBadgeé sobre responsabilidade e não se aplica. Rejeitadas: avatar stack (presume conta); contagem/ranking (intenção é qualitativa —Dados: N/A).
Fases verificáveis
- Schema/server — view model + bundle + helpers + route + wrapper
createMunicipalityLeadership+ int tests (toda a lógica de domínio é reuso: B34 toggle, wizard create; o que é novo é a superfície município + reconcile). - UI — coluna + picker +
MunicipalityListLeadershipsControl(shape → craft → critique → polish, Impeccable B) + provider + cards mobile. - Gates — unit tests (controle + colunas),
pnpm gate:fastna iteração,pnpm pushno fechamento; entrada curta emdocs/CHANGELOG-AGENTS.md.
Rabbit holes / Não escopo (engenharia)
- Generalizar
MunicipalityAdvisorCreateProviderem um bridge genérico — 2 call sites, não abstrair (mirror). - Sync bidirecional / campo novo — cortado pela Opção B (sem migration).
- Filtro/ordenação por liderança no header — fora de escopo (a intenção não pede; o gatilho análogo B29 é da dobradinha).
- Server-side search das opções (catálogo grande) — v1 carrega o conjunto visível como
getEligibleAdvisorOptions; se ficar pesado, trocar para busca server-side tiposearchActivityLeadershipOptions(gatilho de revisitação, não fazer agora). - e2e do fluxo completo — opcional na fase 3 (o e2e de municípios existe; decidir na execução se o custo cabe no appetite).
Riscos e mitigação
- Assessor adiciona liderança fora da carteira →
assertMunicipalitiesWithinScope(B34/create) rejeita comLEADERSHIP_MUNICIPALITY_SCOPE_MESSAGE(allowlisted) + rollback otimista. - Remover o último município de uma liderança → floor de 1 do
nextMunicipalityIdsAfterLeadershipMembership→LEADERSHIP_MUNICIPALITY_FLOOR_MESSAGE(allowlisted); chip volta (rollback). - Cap
MAX_LEADERSHIP_MUNICIPALITIES(30) →LEADERSHIP_MUNICIPALITY_CAP_MESSAGE(allowlisted). - Concorrência no toggle → lock advisory
leadership-municipalities:{id}já presente no B34. - Criação de pessoa duplicada →
Contactdedup por telefone +LEADERSHIP_DUPLICATE_MESSAGE(allowlisted); toast no popover. MunicipalityListViewModelconsumido por outros surfaces → campo novo opcional com default[]; nenhum consumidor quebra.- Branch/worktree: o worktree está na branch
plan/b157-…com um edit não commitado do plano B157. Ao executar, criaragent/359-liderancas-coluna-municipiosa partir deorigin/main; o edit do B157 fica preservado (não commitar) — confirmar com o humano como tratar.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (coluna staff, chips, popover, criação inline, scopes)
- Invariantes AGENTS/engineering-standards: sem migration, sem collection nova, access reusado (
overrideAccess: falseonde o ator importa), transação nas escritas multi-collection (já nas actions reusadas), copy pt-BR / identificadores em inglês - Testes de domínio: int spec novo (
campaignMunicipalityLeadershipList.int.spec.ts— toggle e create pela superfície município, scopes advisor/coordinator/leader, floor/cap, duplicata) + unit do controle
Pós-revisão (/simplify, 3 revisores paralelos — read-only)
Aplicados: reconcile scoped reusando loadMunicipalityLeadershipSummaries nas duas wrappers (elimina o único bypass novo e o gêmeo da query reversa; o create devolve o nome real do contato — contactReused — para o chip otimista); toggle passa a revalidar /campanha/liderancas (a rationale do B34 não transfere: o chamador NÃO está nessa lista); validação cliente espelha o schema (nome maxLength 120, telefone via normalizeBrazilianPhone); copy "staff" → "a equipe"; ids do mini-form via useId (tabela + cards mobile são árvores irmãs); refoco no CommandInput ao fechar o form (foco não cai no body). Deferidos com gatilho: query reversa do bundle fora do Promise.all (1 RTT serial no caminho crítico — otimizar se a lista ficar lenta); slug lookup defensivo pós-commit do create.