11 KiB
Impl: Generalizar editor e display das colunas de relação na lista de municípios
Status: em execução Atualizado em: 2026-08-05 Issue: #374 Intenção: docs/plans/generalizar-colunas-relacao-municipios.md Appetite restante: ~0,75 dia eng; manter sem migration, rota nova ou mudança de access
Leitura da intenção
- Outcome: Assessores, Lideranças e Dobradinhas devem ter a mesma linguagem de interação na lista de municípios: avatar stack fechado e
CampaignCellEditOverlaycom busca, chips removíveis e criação inline por nome. - O que NÃO negociar: Assessores continua sendo a referência visual; o contrato de props de
MunicipalityListe as regras de visibilidade por papel não mudam; busca com acento, optimistic UI, reconciliação de respostas fora de ordem, erros e bridges de opções recém-criadas continuam funcionando;RelationChipCellpermanece dono dos editores inline fora desta lista. - O que reavaliar: a extração não pode presumir que os três writes usam o mesmo transporte. Assessores e Lideranças usam JSON routes; Dobradinhas usa server actions. Além disso, retirar o telefone da criação inline de Lideranças exige mudar o schema específico e o serviço existente, não somente esconder um campo.
Abordagem recomendada
flowchart LR
ML[MunicipalityList] --> A[Wrapper Assessores]
ML --> L[Wrapper Lideranças]
ML --> D[Wrapper Dobradinhas]
A --> E[MunicipalityRelationEditor]
L --> E
D --> E
E --> O[CampaignCellEditOverlay]
E --> V[MunicipalityRelationAvatarStack]
A --> JA[JSON advisors]
L --> JL[JSON leaderships]
D --> SA[server actions de dobradinhas]
JL --> CR[criação transacional Contact + Leadership]
Opções consideradas: A) editor compartilhado com adaptadores de domínio | B) ampliar RelationChipCell com uma segunda apresentação | C) manter máquinas separadas e compartilhar somente peças visuais
Recomendação: A — concentra a única máquina de optimistic state, sequência de requests, busca, chips e criação, enquanto wrappers pequenos normalizam os transportes e preservam copy, bridges e regras próprias de cada domínio.
Rejeitadas: B porque mistura o editor inline de 813 linhas com outra política de interação e ameaça os call sites fora de /campanha/municipios; C porque entrega aparência igual mantendo três implementações do comportamento crítico, contrariando o aceite interno e deixando regressões divergentes prováveis.
Decisões de engenharia
Contrato do editor
Opções: callbacks genéricos de baixo nível | componente ciente dos três endpoints | contrato normalizado de mutação
Recomendação: contrato normalizado de mutação — o shared recebe entradas { id, label, searchText? }, selectedIDs, copy e callbacks toggle/create que retornam o conjunto confirmado e, na criação, a nova opção. O editor é dono de pending sentinels, sequência, rollback, reconcile, filtro e UI; cada wrapper é dono do transporte e do bridge de catálogo.
Alternativas rejeitadas: callbacks de baixo nível porque vazariam setters e refs, tornando o shared apenas markup; endpoints embutidos porque acoplariam um componente visual às rotas e a server actions incompatíveis.
Display compartilhado
Opções: um avatar stack com entradas normalizadas | manter wrappers visuais duplicados | tornar o editor responsável por iniciais específicas
Recomendação: MunicipalityRelationAvatarStack recebe entradas { id, label, initialsLabel? }, limite e empty state; o editor deriva tooltip e acessibilidade dos labels. Assessores preserva MissingAdvisorBadge, e Dobradinhas informa o nome sem partido em initialsLabel.
Alternativas rejeitadas: duplicação porque já produziu o desalinhamento atual; regras de iniciais dentro do editor porque são apresentação de cada domínio, não estado de edição.
Liderança criada somente com nome
Opções: enviar telefone sintético | tornar telefone opcional em todos os formulários | aceitar somente nome no schema específico e reutilizar o serviço transacional com dedup condicional
Recomendação: o schema estrito de municipalityLeadershipCreateSchema passa a aceitar somente municipalityId + name; o núcleo existente de criação aceita telefone opcional internamente. Como Contact.phone já é opcional no Payload, esse caminho cria um novo Contact com phone: null e a Leadership na mesma transação, após fresh-actor e scope check. O telefone poderá ser preenchido depois na ficha. Com telefone nos demais fluxos, o serviço mantém lock e dedup atuais; os schemas de cadastro completo permanecem fora do escopo desta Issue.
Alternativas rejeitadas: telefone sintético não é necessário e corromperia a identidade/unicidade de Contact, podendo colidir com um telefone real; ampliar a mudança a todos os formulários alteraria outros fluxos e sua política de dedup sem fazer parte do aceite desta lista.
Componentes / mudanças
MunicipalityRelationEditor(src/components/campaign/shared/MunicipalityRelationEditor.tsx): nova dona da máquina compartilhada de overlay, optimistic IDs, requests concorrentes, chips, Command, busca normalizada, criação name-only e erro acessível.MunicipalityRelationAvatarStack(src/components/campaign/shared/MunicipalityRelationAvatarStack.tsx): avatar stack único, máximo padrão de três, nomes para screen reader/tooltip e empty state injetável.MunicipalityListAdvisorsControl: wrapper de opções/copy/JSON e bridge de novos assessores; usa os dois componentes compartilhados sem alterar comportamento ou empty state prioritário.MunicipalityListLeadershipsControl: wrapper de opções/copy/JSON e bridge; remove formulário e imports de telefone, cria diretamente pelo nome pesquisado e usa avatar stack no trigger.MunicipalityStateDeputyRelationCell: trocaRelationChipCellpelo editor compartilhado; adaptacommitAction/createAction, mantém busca por nome e partido, links dos chips quando aplicável e nomes sem partido nas iniciais.- Criação de liderança (
src/lib/schemas/leadership.ts, route esrc/app/(campaign)/campanha/actions/leadership.ts): o input inline envia apenas nome e persisteContact.phone = null; mantém transação, fresh actor, escopo, defaults e revalidações existentes, sem telefone stub. - Código substituído: remover os avatar stacks locais e a máquina duplicada que ficar órfã;
RelationChipCellpermanece porque ainda serveLeadershipStateDeputyRelationCelleMunicipalityPortfolioCell. - Migration: sem migration;
Contact.phonejá é opcional. - Access / Consent: nenhuma política nova. O novo caminho usa o mesmo staff gate, fresh actor, scope check e transação; não há opt-in ou Consent neste fluxo interno.
- UI: Impeccable B; replicar exatamente shape/craft da coluna Assessores em desktop Popover e mobile Drawer, depois criticar foco, target de 44 px, tooltip, live region, overflow e estados vazio/pending/error.
Fases verificáveis
- Tracer / contrato server — ajustar e testar a criação inline name-only de Liderança no serviço existente; provar
Contact.phone === null, vínculo ao município, bloqueio de papel/escopo e preservação do caminho completo com telefone. - Editor e display compartilhados — extrair primeiro Assessores como referência; manter testes de overlay, optimistic reconcile, rollback, criação e busca antes de migrar os demais wrappers.
- Lideranças e Dobradinhas — migrar ambas; confirmar avatar stack/tooltip, criação name-only, busca por acento e por partido, remoção, criação e adapters JSON/server action em Popover e Drawer.
- Polish e gates — revisar os três call sites em desktop/mobile, eliminar código morto e executar
pnpm gate:fast; no fechamento,/simplify, captura de débitos e push viapnpm push.
Estratégia de testes
- Unit do editor compartilhado: render fechado, Popover/Drawer, busca normalizada, toggle/remove, criação otimista, resposta fora de ordem, rollback e erro/live region.
- Unit dos wrappers: copy e payload de cada domínio, bridge da opção criada, Lideranças sem campo de telefone, Dobradinhas pesquisável por partido e adaptação do resultado da server action.
- Unit de composição:
MunicipalityListmantém visibilidade por papel e passa a renderizar as três pilhas com iniciais, limite e nomes acessíveis. - Integração server: caminho name-only cria
Contact+Leadershipatomicamente e respeita staff/scope; caminho geral com telefone continua deduplicando pelo telefone.
Rabbit holes / Não escopo (engenharia)
- Não migrar
LeadershipStateDeputyRelationCell,MunicipalityPortfolioCellnem outros call sites deRelationChipCell. - Não unificar JSON routes, server actions, providers de criação ou tipos de domínio só para obter uma API uniforme.
- Não mudar visibilidade de colunas, URLs, collections, Payload schema, Consent ou regras de access.
- Não generalizar o componente para relações fora da lista de municípios; gatilho para revisitar: outro editor Popover repetir a mesma máquina completa.
- Não alterar os cadastros completos de liderança nesta Issue; o atalho inline da lista cria somente com nome e a ficha recebe o telefone real depois.
Riscos e mitigação
- Abstração larga demais: props excessivas podem esconder três políticas diferentes. Mitigar com um resultado normalizado pequeno, wrappers de domínio e testes do componente pelo comportamento, não pela implementação.
- Concorrência otimista: extração pode perder a regra de maior sequência confirmada. Mitigar movendo a máquina como uma unidade e pinando resposta fora de ordem + falha concorrente em unit test.
- Criação somente com nome: não há dedup confiável por pessoa sem identificador. Mitigar criando um novo
Contactdeliberadamente com telefone nulo, deixando o telefone real para a ficha e não usando stub nem dedup por nome. - Server action versus JSON: erros têm formatos diferentes. Mitigar nos adapters, que convertem ambos para o mesmo success/error do editor sem expor
FormDatano shared. - Acessibilidade responsiva: trocar o trigger pode quebrar tooltip, foco ou Drawer compartilhado. Mitigar reutilizando
CampaignCellEditOverlaysem alterações de contrato e ampliando a matriz existente de testes Popover/Sheet para Dobradinhas.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto
- As três colunas usam um único editor e um único avatar stack
- Criação de liderança envia somente nome e persiste telefone nulo sem afrouxar outros formulários
- optimistic state, resposta fora de ordem, erro, busca e criação cobertos por testes
- Invariantes AGENTS/engineering-standards preservadas
- Sem migration, rota nova, mudança de props de
MunicipalityListou regressão de access
Self-score decision-quality
5/5 — decisões caras registram opções e rejeitadas; a abordagem cabe no appetite com cortes explícitos; rabbit holes estão nomeados; reutiliza os donos existentes; o outcome e os lockdowns da intenção permanecem intactos.