15 KiB
Impl: Pessoas — edição onde você vê (edit-where-you-see) na lista desktop
Status: aprovado Atualizado em: 2026-08-11 Issue: #655 Intenção: docs/plans/pessoas-edicao-inplace-lista.md Appetite restante: ~1,5–2 dias eng; um outcome verificável — a linha da lista é editável sem sair da tabela
Leitura da intenção
- Outcome: na tabela desktop de
/campanha/pessoas, toda célula (exceto Ações) é um input permanente sem destaque — parece texto, se comporta como input; salva no blur/Enter (Esc descarta); Nome mantém o valor como link; colunas de municípios (Assessora, Lidera, Aliada em) e Assessorado usam chips internos com colapso por território ("Sertão do São Francisco (5)"), grupo "Salvador (19)", "+X" expande, X no hover remove; ações ganham tooltip. - O que NÃO negociar: sem migration (escreve no dono da ficha —
Contactnome/telefone/e-mail/cidade; vínculos nas collections donas); leader fora da rota; escopo do assessor preservado (só a carteira dele); mobile intacto; nada criado fora do catálogo (texto sem match não vira chip); link do Nome navega; "—" vira placeholder apagado. - O que reavaliar: a hipótese de reusar
CampaignInlineEditableCell(B163) — seueditTrigger='cell'tem estado de edição explícito; o paradigma travado exige input sempre montado, então a mudança é um modo novo no componente compartilhado, não um ajuste do modo existente. A hipótese de reusarMunicipalityPortfolioCell/RelationChipCellconfirma-se: colapso por território já existe (chips batch); o trabalho novo é expandir chip batch por clique/hover (interação que nenhuma célula do sistema tem hoje), o grupo "Salvador (19)" (zona-cidade completa) e o modoquiet(sem tint de hover/foco).
Abordagem recomendada
flowchart LR
L[lib/municipalityPortfolio: grupo Salvador + expand chips] --> M[MunicipalityPortfolioCell: opt-ins quiet/+X/expand]
M --> P[PeopleMunicipalityCell: estado de expansão + colapso no mouse-leave]
C[CampaignInlineEditableCell: modo permanent] --> T[Células de texto: Nome link-overlay, Contato, E-mail, Base]
R[RelationOptionCell: Assessorado readOnly + quiet] --> A[PeopleAssessoradoCell]
S[Actions: updatePersonContact, setPersonAssessora, setPersonAdvisor] --> F[pessoas/formActions.ts]
T --> PG[page.tsx: colunas com matriz de edição por papel]
A --> PG
P --> PG
Opções consideradas:
- A — estender os componentes compartilhados com props opt-in (
CampaignInlineEditableCellmodopermanent;RelationChipCellcomquiet/onChipClick/overflowToggleLabel;MunicipalityPortfolioCellrepassa e expande chips; novo grupo nobuildMunicipalityPortfolioChips): uma máquina de save e uma máquina de chips para todo o sistema; as outras listas ficam intactas (defaults inalterados). - B — componentes novos
people/*que duplicam a máquina de save/chips: isolamento total, mas dois donos para blur/Enter/Esc/pending/erro e para o combobox ARIA — exatamente o twin que o repo proíbe. - C — modo
permanentvirar o novo default do B163: coerente com o paradigma, mas muda o comportamento visual das dobradinhas/lideranças sem ser pedido deste item.
Recomendação: A — o trabalho de interação nova (expandir chip batch, +X, quiet) entra como opt-in nas máquinas existentes e a expansão fica como estado de apresentação do wrapper PeopleMunicipalityCell (puro, sem tocar o ciclo de commit do RelationChipCell). C é rejeitada porque altera superfícies fora do escopo; B porque cria twin.
Componentes / mudanças
Puro (lib, client-safe):
src/lib/municipalityPortfolio.ts: (1) novo kind de chipcity— zonas de uma zona-cidade completas viram UM chip{ kind: 'city', label: 'Salvador', city: 'Salvador', municipalityIds: [19 ids] }, checado antes do colapso por território (senão as 19 zonas colapsariam como "Metropolitano de Salvador (19)");MunicipalityPortfolioChipganha o variant; (2) helper puroexpandMunicipalityPortfolioChips(chips, expandedKeys)— substitui chip batch (territory/city) cuja key está expandida pelos chips municipais membros; (3) testes unit.src/lib/schemas/contact.ts: variantecitynocontactFieldUpdateSchemacompartilhado (bounds da collection: 2–100; aditivo — as actions de dobradinhas/liderança não expõemcitye continuam falhando em campo desconhecido).
Server (person.ts + formActions):
src/app/(campaign)/campanha/actions/person.ts: três record-functions novas, todaswithPayloadTransaction+req, Local API comuser/overrideAccess: falsee bypass justificado só depois da checagem:updatePersonContactRecord(payload, actor, input)— escopo: irrestrito sempre; assessor somente se pelo menos uma entidade da pessoa (leadership OU stateDeputy, lida comoverrideAccess: false) é gerenciável por ele (regra "edita o que vê" da linha; staff-only → assessor nega). Depois, bypass do Contact (precedente B163/C99).setPersonAssessoraMembershipRecord(payload, actor, { contactID, municipalityIds, assigned })—reloadUnrestrictedActor(canAssignMunicipalityAdvisors é unrestricted-only); transação única: resolve as contas staff da pessoa porcontact, asserta exatamente uma (multi-conta → célula read-only no client; o server nega com mensagem segura), e para cada município: lock advisorymunicipality-advisors:<id>+ toggle — extrair o toggle desetMunicipalityAdvisorMembershipRecord(src/app/(campaign)/campanha/actions/municipality.ts) para um helper compartilhado usado pelos dois (edit the owner, sem duplicar o bloco lock+toggle).setPersonAdvisorMembershipRecord(payload, actor, { contactID, advisorId, assigned })—reloadUnrestrictedActor(regra B156); transação única: aplica o delta de advisor em cada entidade da pessoa (leadership e/ou stateDeputy) vianextAdvisorIdsAfterMembership/helper existente — semântica person-centric: a coluna Assessorado é atributo da pessoa, adicionar/remover atinge os dois vínculos quando ambos existem.
src/app/(campaign)/campanha/(app)/pessoas/formActions.ts(novo):updatePersonContactFormAction,setPersonAssessoraFormAction,setPersonAssessoradoFormAction,setPersonLeadershipMunicipalitiesFormAction(envolvesetLeadershipMunicipalitiesMembership),setPersonStateDeputyMunicipalitiesFormAction(envolvesetStateDeputyMunicipalitiesBatch) — cascasrunCampaignFormActionno padrão das dobradinhas, com safe-messages existentes.- Revalidação:
/campanha/pessoas+ caminhos de detalhe das entidades tocadas (liderancas/[id],dobradinhas/[id], municípios tocados no assessora) — espelhandorevalidateStateDeputyPaths/revalidateLeadershipMunicipalityPaths. src/utilities/people/peopleData.ts:PeopleRowViewModelganhaassessoradoIDs: number[](uniãoleadershipAdvisorIDs ∪ deputyAdvisorIDs, já resolvida hoje para os nomes) — ids que os chips do Assessorado precisam.
UI (Impeccable B — encaixe em tela existente):
src/components/campaign/shared/CampaignInlineEditableCell.tsx: proppermanent?: boolean(default false — B163/dobradinhas/lideranças intactos). Empermanent:- texto (Contato/E-mail/Base): input sempre montado,
bg-transparent border-transparent(mesmo vocabulário decampaignInlineInputClassName), valor = draft, salva no blur/Enter, Esc reverte, vazio →placeholder="—"apagado (o "—" atual vira placeholder), telefone mantém formatação; máquina de save/pending/erro/saved-feedback/requestId reutilizada tal qual. - Nome (
permanent+href): mecanismo travado no gate — input sempre montadoabsolute inset-0 z-0comvaluesempre vazio (bg-transparent), link emz-10compointer-events-autocujo texto renderizadraft || value; cada tecla atualiza o draft no display (texto do link), o valor real do input permanece vazio; clique no link navega; foco por Tab/clique fora do texto → digitação; blur/Enter salva, Esc descarta. Sufixo({party})permanece fora do link como texto read-only. - Indicador de foco discreto:
focus-visiblering suave; nada em hover (paradigma sem fundo/borda).
- texto (Contato/E-mail/Base): input sempre montado,
src/components/campaign/shared/RelationChipCell.tsx: três opt-ins, defaults inalterados (B34/B36/B37/B156/B157/B159/B169 intactos):quiet?: boolean— removepointer-fine:hover:bg-muted/40do container; mantém apenas indicador discreto de foco (guardrail de acessibilidade);onChipClick?: (chip) => void— chip sem href clicável (hoje só navega); com stopPropagation;overflowToggleLabel?: (hiddenCount) => string— o toggle de overflow do B170 renderiza como chip+Nem vez de "Ver mais…".
src/components/campaign/shared/MunicipalityPortfolioCell.tsx: repassa os três opt-ins aoRelationChipCelle aplicaexpandMunicipalityPortfolioChipsnobuildChipsquandoexpandedKeysé passado.src/components/campaign/people/PeopleMunicipalityCell.tsx(novo, substitui oPeopleMunicipalityCelllocal do page.tsx): wrapper deMunicipalityPortfolioCellcom estado localexpandedKeys+onMouseLeaveque colapsa chips expandidos cujos membros continuam todos atribuídos (lêidsda prop via ref); serve as colunas Assessora/Lidera/Aliada comcommitAction/buildFormData/minItems/readOnlydefinidos pela página.src/components/campaign/people/PeopleAssessoradoCell.tsx(novo): wrapper deRelationOptionCell— chips = assessorados com href/campanha/assessores/[id](só para irrestrito; regra B156),optionsdeloadEligibleAdvisorOptions,readOnlypara assessor; copy doADVISOR_COPY(sem o twin: extrair/reusar a copy deLeadershipAdvisorRelationCellse o diff permitir, senão constante local).src/app/(campaign)/campanha/(app)/pessoas/page.tsx: colunas Contato/E-mail/Base comCampaignInlineEditableCell permanent; Nome compermanent+href(/campanha/liderancas/[id]quandoleadershipID); Assessora/Lidera/Aliada comPeopleMunicipalityCell; Assessorado comPeopleAssessoradoCell; matriz de edição por papel (helper puro na page oulib): irrestrito edita tudo; assessor edita células de texto e Lidera/Aliada (comaddableIds = administeredIds,minItems=1em Lidera) apenas nas linhas cujo vínculo cruza a carteira; Assessora e Assessorado read-only para assessor (canAssignMunicipalityAdvisors / B156 são unrestricted-only). Ações:CampaignHoverTooltipcom a label (WhatsApp, Convidar, Apagar) nos três botões.PeopleMobileCardsintacto.- Migration: nenhuma — sem mudança de schema.
Dados → forma
- Forma escolhida: inputs permanentes sem destaque + chips internos ao input — o paradigma travado no gate 2026-08-11, que É a forma deste item (não há dado analítico; o chip de território mostra contagem, não métrica). Rejeitadas: toggle global de edição, lápis obrigatório e células read→edit com estado visual — tudo divergente do aceite.
Fases verificáveis
- Tracer / puro + UI machines (~1/2 appetite): grupo
cityde Salvador +expandMunicipalityPortfolioChips+ unit tests; opt-ins noRelationChipCell/MunicipalityPortfolioCell; modopermanentnoCampaignInlineEditableCell;PeopleMunicipalityCell+PeopleAssessoradoCell. Validar que dobradinhas/lideranças não regridem (testes existentes + revisão visual). - Server / access (~1/3 appetite): variante
cityno schema; as três record-functions + formActions;assessoradoIDsno VM; int tests — coordenador/candidato editam tudo, assessor só a carteira (célula de texto em linha em escopo ok; linha staff-only negada; Lidera/Aliada com addableIds; Assessora/Assessorado read-only), multi-conta do Assessora nega, union do Assessorado escreve nas duas entidades, telefone conflitante falha com mensagem segura. - Page + polish (~1/3 appetite): colunas com a matriz por papel, tooltips nas ações, indicador de foco discreto,
+X, colapso por mouse-leave; shape→craft→critique→polish. - Gates: após cada slice
pnpm exec tsc --noEmit+ testes focados; ao finalpnpm lint(0 warnings),pnpm format:check,pnpm exec knip,pnpm check:cycles,pnpm test,pnpm test:e2e(se tocar jornada),pnpm buildlocal.
Rabbit holes / Não escopo (engenharia)
- Contenteditable real para chips internos — o comportamento continua o de input (chips como dados, teclado previsível); a mecânica é chips + input inline do
RelationChipCell. - Estado de expansão global / animações entre linhas — expansão é local à célula, por hover/foco, sem estado persistido.
- Tree-view de território com sub-chips persistentes — grupo colapsa/expande in loco; nada de hierarquia.
- Edição em lote / spreadsheet mode / reorder de colunas / coluna nova.
- C112 (telefones múltiplos) e B155+ (rota em vez de form action) continuam suaves — o editor de Contato segue o shape atual e o padrão de escrita vigente (form action).
- Migration de schema — nenhuma.
Riscos e mitigação
- Regressão B163/dobradinhas/lideranças: modo
permanentdefault-off; testes existentes do controle compartilhado cobrem os modos antigos; revisão visual das duas listas na Fase 1. - Regressão
RelationChipCell(B34/B36/B37/B156/B157/B159/B169): três props opt-in com defaults inalterados; testes unit/int existentes das células de relação rodam intactos na Fase 1. - Mecanismo do Nome (input vazio + draft no link): caret invisível é trade-off do mecanismo travado; a navegação e a digitação coexistem; teste de componente cobre clique-no-link (navega) vs clique-fora (edita), Enter/Esc/blur.
- Assessor com linha visível por capacidade fora da carteira: matriz por coluna derruba a edição quando a entidade subjacente não é gerenciável (Lidera/Aliada read-only na linha); o server nega de qualquer forma (access da collection dona).
- Pessoa com múltiplas contas staff (Assessora): célula read-only + server nega; edge raro e honesto.
- Chips batch (território/Salvador) removidos no X removem o grupo todo: semântica já existente no sistema; o undo toast cobre a remoção em lote.
- Revalidação de paths novos (
/campanha/pessoas+ detalhes das entidades): seguir os helpers de revalidação existentes por entidade; nuncarevalidatePathglobal.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (inputs permanentes, Nome-link, chips com colapso por território/Salvador, +X, X no hover, tooltips, mobile intacto, sem lote)
- Sem migration; escrita no dono da ficha (
Contact) e nas collections donas dos vínculos - Local API com
user+overrideAccess: false; bypass do Contact/entities justificado após checagem de escopo; transações comreqem toda escrita multi-collection - Escopo do assessor preservado (matriz por coluna + access da collection dona); leader fora da rota; multi-conta do Assessora nega
contactFieldUpdateSchemaganhacityde forma aditiva; mensagens seguras allowlisted- Testes previstos: unit (grupo Salvador, expand chips, +X) e int (escopo de célula por papel, assessora single-account, union do assessorado, telefone conflitante)
- Nome em identificadores inglês; copy pt-BR
Self-score decision-quality: 5/5 — decisões caras (estender vs criar twin, mecanismo do Nome, semântica do Assessorado/Assessora) têm alternativas rejeitadas com justificativa; appetite bounded por fases; rabbit holes nomeados; reuso máximo das máquinas existentes; o aceite da intenção não foi alterado.