O teste 'assigns and removes multiple municipalities in one batch' escolhia o segundo município com id not_equals cru; sob ~48 workers paralelos podia cair num município que um spec paralelo (cap 10 do B27/B154) acabara de encher, fazendo o batch estourar o teto. getMunicipality() aloca município globalmente único e purga resíduo.
19 KiB
Impl: Criar assessor inline no popover da lista de municípios
Status: aprovado Atualizado em: 2026-08-03 Issue: #352 Intenção: docs/plans/criar-assessor-inline-popover-municipios.md Appetite restante: herdado (~0,5 dia eng)
Leitura da intenção
- Outcome: o coordenador cria uma conta
campaignUsercom papeladvisorsó com o nome, dentro do popover "Atribuir assessores" de/campanha/municipios, com atribuição automática ao município atual; chip otimista, campo limpo, popover aberto; erro visível no próprio popover quando a criação falha; a conta não faz login até um coordenador trocar credenciais em/campanha/assessores/[id]. - O que NÃO negociar: não é formulário completo (anti-goal: sem e-mail/celular/senha/foto inline); papel sempre
advisor; indisponível paraleader(que já não vê o popover — a lista de elegíveis éeligibleCampaignStaffWhere); e-mail stub<slug-do-nome>@criado.invalid(padrão E4R, travado no gate 2026-08-03); faceta?advisor=reconcilia só na próxima navegação (contrato B24/B27); dedup por similaridade de nome fica de fora. - O que reavaliar:
- A intenção fala do "
advisorLookup(memo doMunicipalityListAdvisorsControl) incluir o assessor recém-criado". Um memo por instância só cobre a linha que criou — o coordenador abre o popover de outro município na mesma reunião e o assessor novo precisa estar lá. Isso exige estado compartilhado entre linhas (provider client), não só o memo. - Colisão do e-mail stub não foi decidida no gate: dois nomes com o mesmo slug (
João× 2) gerariam o mesmojoao@criado.invalide oemailéunique. Precisa de dedup determinístico. - "Estado otimista" do chip: o id do assessor não existe até a resposta — o otimismo exige um id temporário, disjunto dos ids reais.
- A intenção fala do "
Abordagem recomendada
flowchart LR
cmd["Command: digita 'Carlos'<br/>sem match"] -->|"filteredOptions == 0<br/>e query ≥ 2"| createItem["+ Criar assessor 'Carlos'"]
createItem -->|"Enter/clique"| optimistic["temp id negativo no selectedIDs<br/>+ pendingCreates + spinner"]
optimistic --> post["POST /campanha/municipios/advisors<br/>body { municipalityId, name }"]
post --> route["body union: 'name' in body?"]
route -->|"create"| record["createMunicipalityAdvisorRecord<br/>(mesma transação + lock)"]
record -->|"1) probe stub livre"| u["payload.create campaignUser<br/>(user + overrideAccess:false + req)"]
u -->|"2) cap via nextAdvisorIdsAfterMembership"| m["payload.update municipality.advisors"]
record --> resp["{ advisors, createdAdvisor: { id, name } }"]
resp -->|"settle (0 pendências)"| adopt["adota set confirmado<br/>+ registra no provider"]
post -.erro.-> alert["revert temp + Alert no popover"]
Opções consideradas: ver "Decisões de engenharia" (D1–D6).
Recomendação: endpoint sobrecarregado com body-union; record novo no mesmo arquivo da action do toggle (transação única: cria conta + atribui, cap com rollback); provider client para o assessor criado virar opção em todas as linhas; chip otimista com id temporário negativo reusando o maquinário de seq/pendências do B27.
Rejeitadas: rota nova (advisors/create); reusar createAdvisorRecord do B19 fora de transação; estado local por instância; router.refresh() após criar; aguardar a resposta para mostrar o chip; deixar o unique violation virar erro.
Decisões de engenharia
D1 — Endpoint.
Opções: A) sobrecarregar POST /campanha/municipios/advisors com body-union toggle | create | B) rota nova advisors/create | C) um objeto único com name/advisorId opcionais + superRefine.
Recomendação: A — é a decisão travada no gate, e a union é type-honest: os dois shapes são mutuamente exclusivos, impossível enviar name + assigned: false. O toggle existente fica byte a byte igual ('name' in body ramifica).
Rejeitadas: B — duplica o shell campaignJsonMutationRoute (guarda de origem, parse, mapeamento de erro) e contraria o gate; C — permite combinações impossíveis e o tipo não reflete o contrato.
D2 — Onde cria a conta.
Opções: A) createMunicipalityAdvisorRecord em actions/municipality.ts (mesmo arquivo do toggle), na MESMA transação do assign | B) reusar createAdvisorRecord (B19) + toggle separado | C) server action de formulário.
Recomendação: A — uma transação (withPayloadTransaction) cria o campaignUser e atribui ao município: se o cap de 10 estoura, o rollback não deixa conta órfã. Reusa acquireTextAdvisoryLocks(['municipality-advisors:{id}']), nextAdvisorIdsAfterMembership (fonte única do cap), hookFilledCreateData, randomBytes, reloadUnrestrictedActor com a mensagem de membership.
Rejeitadas: B — createAdvisorRecord não recebe req (fora de transação), revalida caminhos do B19 e não atribui; C — form action fecha popover/toast, exatamente a razão do B27 ter escolhido endpoint JSON.
D3 — E-mail stub e colisão.
Opções (colisão): A) probe determinístico de e-mails livres na transação (joao@criado.invalid, joao-2@…, joao-3@…) | B) deixar o unique violation virar erro genérico | C) sufixo aleatório.
Recomendação: A — o "Criar assessor 'João'" sempre funciona (nome não é unique, conta duplicada de nome é legal); helper puro stubCampaignUserEmailFor(name, occurrence) testável; probe por equals em loop bounded (sem semântica de like). Bônus (mesmo comportamento do aceite): generalizar o predicado de placeholder para cobrir @criado.invalid além de @planilha.invalid — assim o reset de senha (PLACEHOLDER_RESET_MESSAGE) e a célula de e-mail de /campanha/assessores (AdvisorDebouncedTextCell) tratam stubs inline como os do seed E4R.
Rejeitadas: B — mensagem enganosa (o coordenador digitou nome, não e-mail) e colapsaria para o genérico; C — não determinístico, pior para reconciliação futura.
D4 — Estado compartilhado entre linhas.
Opções: A) provider client MunicipalityAdvisorCreateProvider montado em MunicipalityList (server) envolvendo mobile + tabela, com children server | B) estado local por instância do control | C) router.refresh() após criar.
Recomendação: A — o assessor criado vira opção selecionável em QUALQUER linha no mesmo carregamento de página (decisão travada no gate); mesmo padrão do CampaignListSheetProvider já existente; contexto atravessa componentes server entre provider e células client.
Rejeitadas: B — só a linha criadora conhece o novo assessor, fura o aceite quando o coordenador abre o popover de outro município; C — refresh RSC no meio de delta otimista pode clobber estado em voo e diverge do contrato B27 "reconcilia na próxima navegação" (a página é dinâmica; a navegação seguinte já re-query o getEligibleAdvisorOptions).
D5 — Chip otimista.
Opções: A) id temporário NEGATIVO no selectedIDs (disjunto dos ids reais) + mesmo maquinário seq/pendingCountRef/latestConfirmedRef; X oculto no chip temporário | B) aguardar a resposta e só então adicionar o chip real.
Recomendação: A — "chip aparece imediatamente (estado otimista)" é aceite explícito; o settle reusa finishRequest (adota o set confirmado com o id real quando 0 pendências); falha reverte o temp id como o toggle reverte. X oculto no temp: não há como cancelar um create server-side a meio voo; remoção real após o settle. Guard advisorId < 0 no toggle (belt-and-suspenders: id temporário nunca vira POST).
Rejeitadas: B — o chip demora um round trip (~150 ms) contra o instantâneo dos toggles; o aceite pede otimista.
D6 — Schema do nome.
Opções: A) z.string().trim().min(2).max(160) inline em schemas/municipality.ts | B) extrair advisorNameSchema em schemas/advisor.ts e importar.
Recomendação: A — schemas/advisor.ts já importa de schemas/municipality.ts (MAX_ADVISORS_PER_MUNICIPALITY…); extrair criaria ciclo de import (madge check:cycles é gate). A regra tem 1 linha; a divergência futura seria intencional por tela.
Rejeitadas: B — ciclo.
Componentes / mudanças
stubCampaignUserEmailFor(src/lib/schemas/advisor.ts):slugify(name)+ sufixo@criado.invalid, com-{occurrence}a partir da 2ª ocorrência. Ao lado deplanilhaPlaceholderEmailForAdvisor(mesmo módulo de e-mails stub). Predicado de placeholder generalizado (cobre os dois sufixos, case-insensitive) — mesmo nome de export, doc comentada.municipalityAdvisorCreateSchema(src/lib/schemas/municipality.ts):{ municipality: positiveRelationshipId, name: z.string().trim().min(2).max(160) }+ tipoMunicipalityAdvisorCreateInput.createMunicipalityAdvisorRecord/createMunicipalityAdvisor(src/app/(campaign)/campanha/actions/municipality.ts): transação —reloadUnrestrictedActor(mensagem de membership) → lock → probe de stub livre (loop bounded porequalscomoverrideAccess: true+req) →payload.create(campaignUser,user: currentActor,overrideAccess: false,req; dadoshookFilledCreateData<'campaignUser'>com nome +role: 'advisor'+ stub +password: randomBytes(24).toString('base64url')) →findByIDatual →nextAdvisorIdsAfterMembership(current, created.id, true)(cap → throw → rollback sem órfão) →payload.update(overrideAccess: true+req, comentário de bypass como no toggle). Retorna{ advisors, createdAdvisorId }. Export não revalida (contrato do endpoint).route.ts(src/app/(campaign)/campanha/(app)/municipios/advisors/route.ts):bodySchemavira uniontoggle | create; handler ramifica; resposta do create{ status: 'success', message: 'Assessor criado e atribuído.', advisors, createdAdvisor: { id, name } }.safeMessagesinalterado (cap + unrestricted já estão lá).types.ts:MunicipalityListAdvisorsResponsesuccess ganhacreatedAdvisor?: { id: number; name: string } | null.MunicipalityAdvisorCreateProvider.tsx(novo, client,src/components/campaign/municipality/): contexto{ createdOptions: EligibleAdvisorOption[], registerCreatedAdvisor }; registro deduplica por id. PadrãoCampaignListSheetProvider.MunicipalityList.tsx(server): envolveMunicipalityListMobileSection+CampaignTableno provider (children server — padrão de client provider com slots server).MunicipalityListAdvisorsControl.tsx: quandofilteredOptions.length === 0— sequery.trim().length >= 2, umCommandItem"Criar assessor ''" (UserPlusIcon) ANTES do "Nenhum resultado"; senão, "Nenhum resultado" como hoje.createAdvisor(name):setErrorMessage(null), temp id-seqemselectedIDs,pendingCreates(Map tempId→nome) no lookup do memo,setQuery(''), maquinário de pendência/seq; POST{ municipalityId, name }; sucesso →latestConfirmedRef(se seq mais novo) +registerCreatedAdvisor({ id, name, isCurrent: false })+ remove temp dopendingCreates; falha → remove temp deselectedIDs/pendingCreates+reportFailure.effectiveOptions = [...options, ...createdOptions](do provider) alimenta o filtro e o lookup. Chip temporário renderiza semXIcon(indisponível enquanto pendente);togglerecusaadvisorId < 0.- Migration: nenhuma (campos existentes).
- Access / Consent: nenhum novo — create passa por
canManageCampaignUsers(overrideAccess: false+user); semConsent(conta interna de staff, precedente B19).
Dados → forma
N/A — affordance de escrita sobre municipality.advisors via criação de campaignUser; nenhuma métrica, série, ranking ou mapa novo (a intenção já declara Dados: N/A).
Fases verificáveis
- Schema/server (maior parte do appetite): helpers puros + schemas → action record → route/types. Unit dos helpers; int do record.
- UI: provider + control (opção de criar, temp chip, registro no provider). Unit de componente (render da opção sem fetch).
- Gates:
pnpm gate:fastna iteração; e2e do fluxo completo;pnpm pushno fechamento (com o*-impl.mdno commit).
Testes
- Unit:
stubCampaignUserEmailFor(slug sem acento viaslugify,-2na 2ª ocorrência); predicado generalizado (@planilha.invalide@criado.invalid, case-insensitive); parse da union do route (toggle semname→ caminho antigo; create semadvisorId→ caminho novo; shapes inválidos 400). - Int (
tests/int/campaignMunicipalityAdvisorMembership.int.spec.tsou spec irmão): coordinator/candidate criam + atribuem (conta criada comrole: 'advisor'+ stub@criado.invalid, município contém o id); advisor/leader negados; cap 10 → rejeita e não deixa órfão (contagem decampaignUserinalterada após o erro); mesmo nome duas vezes → segundo com stub-2. - Unit componente (
tests/unit/campaignCellEditOverlay.unit.spec.ts/campaignComponents.unit.spec.ts): options vazias + query ≥ 2 → item "Criar assessor" presente; query < 2 → "Nenhum resultado". - E2E (
tests/e2e/campaignMunicipalities.e2e.spec.ts): abrir popover, digitar nome sem match, Enter, chip aparece, reabrir → persistiu. A rota já está no prewarm desetup.e2e.spec.ts(mesmo path do B27).
Rabbit holes / Não escopo (engenharia)
- Formulário completo inline, e-mail/celular/senha/foto no popover →
/campanha/assessores/[id]. - Dedup por similaridade de nome ("Maria" vs "Maria Silva") → fora do appetite, coordenador verifica (decisão de produto).
- Faceta
?advisor=e ordenação em tempo real → contrato B24/B27. - Revalidação de
/campanha/assessoresapós criar → página dinâmica; reconcilia na próxima navegação. - Temp id nunca pode vazar num POST: guard
advisorId < 0notoggle+ X oculto no chip temporário. - Probe de stub:
equalsem loop bounded, nãolike(semântica de curinga em e-mail).
Riscos e mitigação
- Interação temp chip × reconcile existente: temp id negativo é disjunto dos ids reais;
finishRequestadota o set confirmado (id real) quando 0 pendências — o chip nunca duplica nem some antes da hora. - Create dentro de transação + access:
canManageCampaignUsers→getFreshCampaignUser(req)precisa que ouserseja casado noreqda transação — mesmo padrão já em produção nocreateActivityRecord(user+overrideAccess: false+req); se quebrar, falha fechada (403), não fail-open. Int tests com coordinator/candidate cobrem o caminho feliz. - Colisão de stub rara mas real: probe determinística na transação; fallback (unique violation inesperado) colapsa no
genericMessage— aceitável. - Flakiness E2E pré-existente sob carga: rodar o spec isolado na validação final (padrão do time).
Aceite de engenharia
- Aceite de produto da intenção coberto: cria
advisorsó com nome no popover; atribuição automática; chip otimista; erro no popover (Alert existente); sem login até credenciais reais (stub@criado.invalid+ senha aleatória, reset bloqueado como placeholder);leaderintocado; faceta reconcilia na próxima navegação - Invariantes AGENTS/engineering-standards: transação +
reqem escrita multi-collection;overrideAccess: falsecomuserno create; identificadores em inglês / strings pt-BR; sem migration; semConsentnovo - Testes de domínio: unit (stub/predicado/union), int (roles, cap com rollback sem órfão, dedup), unit componente, e2e
- Gates:
tsc --noEmit,lint --max-warnings=0,format:check,check:cycles(madge),knip,pnpm test,pnpm buildlocal (nunca Neon)
Self-score decision-quality: 5/5 — decisões caras com rejeitadas registradas (D1–D6); cabe no appetite (~0,5 dia); rabbit holes nomeados; depth check reusa shells (transação, locks, nextAdvisorIdsAfterMembership, campaignJsonMutationRoute, Command, useCampaignCellFailureChannel, CampaignListSheetProvider como padrão de provider); aceite de produto preservado.
Simplify (2026-08-03) — aplicado e deferido
Três revisores paralelos (qualidade, reuso/DRY, comportamento) no diff do B154; zero P1. Aplicado no cleanup (comportamento preservado, testado):
effectiveOptionsdedup por id — o provider sobrevive a re-renders server (navegação de sort/filtro re-executagetEligibleAdvisorOptions), então o mesmo assessor podia aparecer duas vezes na lista de opções; dedup no merge.- Guard de create em voo por nome — create não é delta idempotente; re-ativar o mesmo nome com o primeiro em voo criaria uma 2ª conta. Skip se o nome já está em
pendingCreates(o temp chip já sinaliza). finishRequestcompartilhado — o closure de settle era byte-idêntico entre toggle e create; hoisted uma vez no corpo do componente.advisorNameSchemaemprimitives.ts— regra do nome espelhada em 3 pontos (route, schema B154,advisorCreateSchemado B19); módulo folha sem ciclo (madge verde).- Fallback de slug vazio no stub — nome só de pontuação (ex. "!!!") passa
min(2)mas slugifica para""→ e-mail inválido e erro genérico sem saída; cai paraassessor@criado.invalid+ unit test. trimmedQueryhoisted + gate<= 160no item "Criar assessor" (espelha o contrato do servidor).createdAdvisorsem| null— a rota nunca envianull.
Defer com gatilho (não registrar como Issue):
- Probe de stub não-atômico entre municípios (dois coordenadores criando o mesmo nome simultaneamente em municípios diferentes): rollback gracioso + erro genérico. Gatilho: evidência real de colisão (queixa/erro observado).
- Reconcile assume commit na ordem de envio (machinery-wide do B27, toggle compartilha): um interleave raro pode dropar o chip do create até a próxima navegação. Gatilho: chip sumindo observado em produção.
Descartado: renomear isPlanilhaPlaceholderEmail (drive-by de 4 call sites pré-existentes); alias table do E4R no stub (TLDs distintos, sem colisão); payload-types.ts com drift do B134 (regenerado por cada run e2e — pertence à entrega do B134).
Pré-existente documentado (não é débito do B154):
- Raça do batch B19 (
campaignAdvisorManagement.int.spec.ts): o teste escolhia o 2º município comid not_equalscru — podia cair num município que um spec paralelo acabara de encher até o cap 10. Os testes de cap do B154 agravaram a probabilidade. Fixado neste PR:getMunicipality()nos dois municípios (alocação globalmente única + purga de resíduo). - Flake pré-existente
testDatabaseLease×onda0Provision(~1 em 4–5 runs, ~48 workers paralelos):onda0Provision.int.spec.tsgrava os textos Onda 0 (banner "Texto provisório…") na mesma rowlideranca-autopreenchimentoquewithMutableConsentFixturemuta/restaura — os dois specs de infra disputam a row sem coordenação. Reproduz em main limpo; nenhuma relação com B154 (nenhum arquivo deste PR toca consent/lease). Fix exige coordenação entre os dois specs de infra (ex.: onda0Provision respeitar o lease) — fora do escopo desta entrega, registrado aqui para não se perder.