Three debts, no new ID. The fifth JSON control and route arrived without touching F1 — the level movement is an explicit submit, not a debounce — which is exactly the escape clause F2/F3 were parked behind, so they stop being conditional. F2 also changes character: the same-origin check that `isSameOriginRequest` documents itself as owning is copied into five routes, so the one that forgets the line fails open. That is not boilerplate and is not cuttable by appetite. F5 is B42's own deferred trigger firing: it parked the footer slot on "a second control needing explicit submit in a Drawer", and this is that control. What the deferral could not know is that the shell pins "Fechar" while "Registrar movimento" sits below the fold, so the action that discards a typed rationale is the reachable one. Discarded with reasons in the triage: `new Date()` during render (the server re-runs the rules and a 409 is a designed state), and `levelNote` in the 435-row select, already written down in E14's own plan next to `politicalTrend.note`, which has the same shape and must be fixed with it.
20 KiB
Escala e DRY pós-B32 (editar Status de apoio na lista de lideranças)
Status: rascunho Atualizado em: 2026-07-27 Item do roadmap: docs/roadmap.md (Fill-ins abertos, B32+, fill-in de engenharia) Impeccable: A para F1/F2/F3 (sem superfície UI nova; extrai comportamento já entregue sem mudar contrato de rede nem markup visível); B para F4/F5, que mudam o que o usuário ouve e o que ele consegue tocar na casca compartilhada Appetite: ~1,25–1,5 dia eng; F1 é uma auditoria com decisão binária (extrair ou registrar rejeição medida, mesmo formato do B33+); F2/F3 deixaram de ser condicionais quando o 5º call site chegou (E14 ✓); F4/F5 são fases da casca, independentes do resultado de F1 Responsável: —
Dados → decisão → apresentação
- Vou apresentar dados? Não (N/A) — lote de manutenção de três controles de auto-save já entregues; nenhuma métrica, série ou escala nova.
- Anti-goals de dado: N/A.
Contexto
O plano do B32 (autosave-status-lista-liderancas.md) e os dois planos anteriores (autosave-tendencia-lista-municipios.md — B24, combobox-assessores-lista-municipios.md — B27) registraram, cada um, o mesmo "Adiado com gatilho": extração só no 3º call site. Com o B32 entregue (2026-07-26), o gatilho disparou — três controles client-side compartilham a mesma máquina de auto-save por debounce:
src/components/campaign/municipality/MunicipalityListExpectedVotesControl.tsx(B27, cenário de votos)src/components/campaign/municipality/MunicipalityListTrendControl.tsx(B24, status + justificativa)src/components/campaign/leadership/LeadershipListSupportStatusControl.tsx(B32, select único)
A comparação linha a linha dos três (feita nesta triage, capture-review-debts pós-B32) confirma o achado do /simplify/reuse: os três repetem, quase byte a byte —
- Estado:
open,isDirty,isPending,errorMessage. - Refs:
saveTimeoutRef(debounce),abortRef(cancela o fetch em voo),committed<X>Ref(último valor confirmado pelo servidor),lastProps<X>Ref(detecta prop externa vs. eco do próprio save),saveGenerationRef(descarta resposta de um save superado por um mais recente). - Efeito de adoção de props externas (navegação/RSC refresh) que só reage quando o valor muda de fora, comparado por uma função
xEqual/===própria de domínio. - Efeito de cleanup (
clearTimeout+abortRef.current?.abort()) no unmount. save<X>assíncrono: gera geração, aborta o anterior,fetch(ENDPOINT, { method: 'POST', headers, credentials: 'same-origin', signal, body }), fazcastda resposta, reverte para o valor confirmado em erro/exceção, atualizacommitted<X>Refem sucesso — sempre guardado porgeneration !== saveGenerationRef.current.scheduleSave/handleXChange: marcaisDirty, atualiza o rascunho local, reagenda osetTimeout.handleOpenChange: ao abrir, limpa erro/dirty; ao fechar com um save pendente, faz flush (chama o save direto em vez de deixar o cleanup do unmount descartá-lo) — o B32 só ganhou esse flush no/simplifyda própria entrega, espelhando oflushDraftque o B24 já tinha.statusMessagecalculado igual nos três (errorMessage→ "Salvando…" → "Alterações serão salvas automaticamente." → vazio), num<p className="sr-only" aria-live="polite">.
Atualização (2026-07-27, pós-B42 ✓): o container dos três já saiu — shared/CampaignCellEditOverlay.tsx (Popover md+ / Drawer mobile) absorveu Popover/Drawer/trigger/tooltip e LeadershipListSupportStatusControl foi migrado como 4º call site. Isso não consome o F1 (a casca não toca estado, refs, debounce nem fetch — foi o corte deliberado do B42, "só o container"), mas muda duas coisas para a auditoria: os três controles ficaram ~25–40 linhas menores, então a máquina de auto-save é agora a maior coisa duplicada neles; e o /simplify do B42 acrescentou à lista de peças idênticas um 13º item, reportFailure — setErrorMessage + toast.error só quando o overlay já fechou, porque fechar desmonta o Alert/aria-live que carregariam o erro. Ele nasceu copiado nos quatro controles (os três do debounce + assessores) no mesmo passe, o que o torna a peça mais recente e mais óbvia do hook, se F1 concluir "extrair".
Atualização (2026-07-27, pós-E14 ✓ — a triage do fechamento do E14): o gatilho de 5º call site que a "Questão em aberto" abaixo guardava para F2/F3 disparou. MunicipalityListLevelControl (movimento de nível de envolvimento) e POST /campanha/municipios/engagement-level são o quinto controle e a quinta rota da família, e chegaram sem tocar em F1: o controle é de submit explícito, não de auto-save por debounce, então ele não é um 4º corpo da máquina do F1 — mas repete o preâmbulo dos dois lados como qualquer outro. F2 também mudou de natureza nessa contagem: isSameOriginRequest documenta-se como dona da política de CSRF, e a política está copiada em cinco route.ts, então a rota que esquecer a linha falha aberta — é uma verificação de origem que depende de disciplina de cópia, não do tipo. Isso põe F2 no piso de expensive_lock e a tira da condicionalidade a F1. Do lado do cliente, F3 fica igualmente com cinco call sites, e continua valendo só para o transporte (o controle do E14 não tem estado de auto-save para compartilhar).
As diferenças reais, que é o que torna a extração não trivial (achado do /simplify reuse review do B32, 2026-07-26): o shape do valor diverge (VoteEstimateScenarioViewModel objeto com 3 cenários × MunicipalityListSavedPoliticalTrend {status, note} × SupportStatus escalar), display vs. draft existe em dois dos três (o B32 colapsou os dois porque só tem um campo — ver "Decisões travadas" do próprio plano B32) e o B24 tem um guard extra (inFlightTrendRef) para não abortar+reenviar o mesmo payload quando blur e fechamento do popover disparam o mesmo flush.
Um quarto controle, MunicipalityListAdvisorsControl.tsx (B27, chips + Command), não compartilha essa máquina — é delta multi-seleção com requestSeqRef/latestConfirmedRef (fora de escopo, mecânica genuinamente diferente) — mas compartilha com os cinco (incluindo ele e o do E14) o preâmbulo do fetch (credentials: 'same-origin', Content-Type/Accept JSON, cast da resposta) e, do lado do servidor, os cinco route.ts (liderancas/support-status, municipios/political-trend, municipios/expected-votes, municipios/advisors, municipios/engagement-level) repetem o mesmo preâmbulo de rota: isSameOriginRequest(request) → 403 → parseCampaignJsonRequestBody → bodySchema.parse → try/catch com campaignJsonMutationErrorResponse.
Objetivos
- F1 (dominante): decidir, com auditoria de código (não de intenção), se um hook
useCampaignListAutosave<TValue>genérico compensa nos três call sites do debounce — e, se sim, extraí-lo; se não, registrar a rejeição medida (precedente B33+: a auditoria pode derrubar a premissa do plano). - F2 (não é mais condicional; gatilho de 5º call site disparado pelo E14 ✓): extrair o helper de preâmbulo de rota (
guardCampaignJsonMutationRequestou nome equivalente) que combinaisSameOriginRequest+parseCampaignJsonRequestBodynos 5route.ts. A motivação subiu de boilerplate para política: a verificação de origem só vale se toda rota da família a escrever, e hoje escrevê-la é opcional por construção — a que esquecer aceita POST cross-origin em silêncio. Fase mais importante do lote junto com F5, e a primeira a rodar. - F3 (não é mais condicional; mesmo gatilho, menor prioridade que F2): wrapper fino de
fetchcliente (postCampaignJson<TResponse>) para os 5 controles, cobrindo só o preâmbulo comum (credentials/headers/cast), nunca a máquina de estado. - F4 (a11y, entrou pela triage do B42 ✓ em 2026-07-27; independente de F1 "extrair ou não"): a região viva de cada controle é um
<p className="sr-only" aria-live="polite">dentro do overlay, e fechar é justamente o que faz o flush da gravação — então "Salvando…" é anunciado numa região que acabou de desmontar, e o leitor de tela não recebe nada. É o mesmo furo que otoast.errordo B42 tapou para o erro, mas o sucesso e o "salvando" continuam mudos. A casca (CampaignCellEditOverlay) é o lugar natural de uma região que sobrevive à superfície — o que muda o scaffold, e é por isso que é fase deste plano e não do B42. Guardrail: uma região por controle, não uma global por página;escala-dry-pos-b33.mdjá corrigiu uma página com três regiões vivas competindo, e a cura não pode reintroduzir isso. - F5 (slot
footer+formIdna casca; gatilho registrado pelo B42 ✓ e disparado pela triage do E14 ✓ em 2026-07-27; independente de F1): o B42 adiou o slot com o gatilho "um 2º controle precisar de submit explícito num Drawer".MunicipalityListLevelControlé esse controle, e a falta do slot é pior do que o adiado previa — não é só o Sinal (B26) que fica sem migrar. Na folha,CampaignCellEditOverlayfixa umDrawerFootercom "Fechar", enquanto "Registrar movimento" fica no fim de um corpo rolável com select, duas textareas e até dois checkboxes: a ação que descarta está pinada e a que constrói está abaixo da dobra, e "Fechar" joga fora uma justificativa digitada sem perguntar. O precedente de forma é oMunicipalityListSignalControl, que mantém container próprio justamente para pôr o submit noDrawerFootercom "Cancelar" ao lado. Escopo: slot opcionalfooter(maisformId, para o submit viver fora do<form>por HTML padrão), o controle do E14 e o Sinal como call sites, e um caso emcampaignCellEditOverlay.unit.spec.tspinando que a folha comfooternão renderiza o "Fechar" default. Só ovariant="sheet"muda: no Popover o submit já é visível sem rolagem. - Guardrail comum às três fases: zero mudança de contrato de URL/rede e zero mudança de comportamento visível — é refactor puro, testável pelos specs/e2e já existentes (
campaignLeaderships.e2e.spec.ts,campaignMunicipalities.e2e.spec.ts).
Decisões travadas
- Nenhuma travada ainda — este item começa pela auditoria, não pela extração. O precedente imediato (B33+,
escala-dry-pos-b33.md) mostrou a mesma armadilha duas vezes na família de hooks de lista: o plano supôs "os domínios divergem" e a auditoria achou que dois terços da divergência eram cópia acidental, não necessidade. Este plano recusa-se a pré-decidir a forma do hook antes de olhar o código (que já foi feito no "Contexto" acima, mas a decisão de assinatura do hook — genérico porTValuevs. par de callbacksequals/buildRequest/parseResponse— fica para a implementação, com o mesmo filtro que o B33+ aplicou aotoHref). - i18n e naming seguem o AGENTS.md: identificadores em inglês (
useCampaignListAutosaveé o nome de trabalho; pode mudar na auditoria), sem strings visíveis novas.
Questões em aberto
- O hook deve cobrir também o
inFlightTrendRefdo B24 (dedup de blur+close) ou deixar esse guard como responsabilidade do chamador? Opções: (a) o hook expõe umflush()idempotente que já resolve isso internamente (um único caminho de save, chamado por blur ou por close); (b) o hook fica "burro" sobre isso e cada chamador decide se precisa do guard. Recomendação: (a) — o guard existe porque hoje há dois caminhos de código para chegar ao mesmo save (oonBlurdo textarea e ohandleOpenChange); um hook comflush()único elimina a duplicidade na raiz em vez de generalizar o sintoma. Vale a pena F2/F3 se F1 concluir "não compensa"?Resolvida em 2026-07-27 pela ressalva da própria pergunta. A recomendação era (b), não fazer nada se F1 rejeitasse, "com uma ressalva — reavaliar F2/F3 isoladamente só se um 5ºroute.ts/controle chegar antes de alguém revisitar este plano". Chegou: o E14 ✓ entregou o quinto de cada um antes de qualquer auditoria de F1. F2/F3 passam a valer por conta própria, e F2 ganhou um motivo que não existia quando a pergunta foi escrita (falha aberta por omissão, ver Contexto).
Abordagem proposta
flowchart LR
Hook["useCampaignListAutosave<TValue><br/>(shared/, se F1 = extrair)"] --> EV["MunicipalityListExpectedVotesControl"]
Hook --> TC["MunicipalityListTrendControl"]
Hook --> SS["LeadershipListSupportStatusControl"]
Guard["guardCampaignJsonMutationRequest<br/>(campaignJsonMutationRoute.ts, se F2 = extrair)"] --> R1["liderancas/support-status/route.ts"]
Guard --> R2["municipios/political-trend/route.ts"]
Guard --> R3["municipios/expected-votes/route.ts"]
Guard --> R4["municipios/advisors/route.ts"]
Guard --> R5["municipios/engagement-level/route.ts"]
Shell["CampaignCellEditOverlay<br/>(F4 região viva + F5 slot footer)"] --> LC["MunicipalityListLevelControl"]
Shell --> SC["MunicipalityListSignalControl"]
Componentes (condicionais à decisão de cada fase):
- F1 — auditoria primeiro, código depois. Antes de escrever o hook, mapear célula a célula (como o "Contexto" já fez) quais das ~12 peças de estado/ref são idênticas, quais são paramétricas (mudam só de tipo, não de lógica) e quais são genuinamente divergentes (o
inFlightTrendRef, o par display/draft). Só extrair as duas primeiras categorias; a terceira fica exposta como parâmetro do hook (equals(a, b),buildRequestBody(value),parseResponse(json)) ou como responsabilidade do chamador, seguindo a "Questão em aberto" acima. Depth check: o hook não deve importar nada de@/app/(campaign)/campanha/(app)/**/types(os três tipos de resposta são por domínio) — ele recebeparseResponsecomo callback, mesmo padrão deuseCampaignListFilterNavigation(recebetoHref, nunca importa os módulos de URL por domínio). - F2 —
guardCampaignJsonMutationRequest(request, schema)(se aprovado): retorna{ ok: true, body } | { ok: false, response }, combinandoisSameOriginRequest+parseCampaignJsonRequestBody+bodySchema.parsenum só call site por rota. Vive ao lado decampaignJsonMutationErrorResponseemsrc/utilities/campaignJsonMutationRoute.ts. - F3 —
postCampaignJson<TResponse>(url, body, signal)(se aprovado):fetchcom o preâmbulo comum +cast, sem decidir revert/retry (isso fica no hook do F1 ou no chamador). - Migration: sem migration, sem collection, sem server action — puro refactor client + route handler.
Dependências
- Nenhuma de outro plano aberto. Depende só do B32 já entregue (é o item que fecha o gatilho de 3 call sites).
Não escopo
MunicipalityListAdvisorsControl.tsx— mecânica de delta multi-seleção comrequestSeqRef/latestConfirmedRef, genuinamente diferente do debounce single-value; participa só de F2/F3 (preâmbulo de rota/fetch), nunca de F1.- Migrar
SupporterFilters/ActivityFiltersou qualquer filtro de lista — família de hook diferente (useCampaignListFilterNavigation, débito do B33+), não deste plano. - Mudar o comportamento de qualquer um dos três controles (timings de debounce, mensagens, contrato de rede) — puro refactor interno.
Rabbit holes
- "Já que estou generalizando, faço o hook aceitar
TValuetotalmente genérico comdeepEqualembutido." UmdeepEqualgenérico reabre a discussão quevoteEstimatesEqual/trendsEqual/===já resolveram por domínio (cada um sabe o que "igual" significa para o seu shape — ex.trendsEqualnormaliza a nota antes de comparar). Mitigação neste item:equalscontinua um callback do chamador, nunca uma função genérica no hook. - "Enquanto mexo nisso, unifico também o botão/Popover/Field ao redor." O JSX diverge de propósito (número vs. select vs. select+textarea vs. badge de trigger) — um shell visual genérico é o mesmo anti-padrão que
escala-dry-pos-b33.mdjá rejeitou para o<form>dos filtros. Mitigação: só a máquina de estado/efeitos sai do componente; o JSX fica onde está.
Adiado com gatilho
F2/F3 se F1 rejeitar a extração do hook principal.Gatilho disparado em 2026-07-27 pelo E14 ✓ (5ª rota e 5º controle). F2/F3 são fases incondicionais deste plano.MunicipalityListAdvisorsControladotar o preâmbulo de fetch do F3 (se F3 for feito) — hoje ele tem uma política de erro diferente (pendingCountRef/sequência, sem revert único), então adotar herdaria só ofetch+cast, não a lógica de estado; barato, mas não é o call site que motivou o item. Gatilho: F3 concluído e aprovado.- Convergir o corpo de multi-seleção (chips +
Command), não só o container. Contagem as-built, medida na triage do B42 ✓ (2026-07-27), para o próximo leitor não re-derivar:shared/LeadershipStateDeputyRelationCell.tsx(B36 ✓, já emshared/e já parametrizada por um record deCOPY, servindo as duas direções da relação) eMunicipalityListAdvisorsControl.tsx(B27 ✓) repetem o mesmo corpo string por string —w-80 p-0, headerrelative flex flex-col gap-2 p-3 pb-0, Spinner, linha de chipsflex flex-wrap gap-1.5 px-3 pt-2, oBadgede remover (max-w-full cursor-pointer gap-1 pr-1 font-normal hover:bg-destructive/15),Command shouldFilter={false}e a linha vaziapx-3 py-6 text-center.AdvisorMunicipalityCellé uma terceira grafia, mas inline (sem overlay), então não conta como 3º call site do mesmo corpo. Gatilho: um 3º corpo em overlay (B34/B37 são os candidatos nomeados) — e aí a peça de destino é a que já mora emshared/, não uma quarta. Os planos B31/B34 registram este mesmo adiado do lado do widget; esta é a contagem do lado do markup.
Referências
docs/roadmap.md(Fill-ins abertos — B32+)- autosave-status-lista-liderancas.md — o pai do lote (B32 ✓), onde o gatilho "3º call site" foi fechado
- autosave-tendencia-lista-municipios.md (B24) e combobox-assessores-lista-municipios.md (B27) — os outros dois planos que registraram o mesmo "Adiado com gatilho"
- polimento-mobile-lista-municipios.md (B42 ✓) — extraiu o container dos mesmos três controles (
CampaignCellEditOverlay) e introduziureportFailurenos quatro; leia o "As-built" antes de auditar o F1 - escala-dry-pos-b33.md — precedente direto de forma: hook via callbacks (não módulos de domínio), auditoria derrubando a premissa do plano antes de escrever código
src/components/campaign/municipality/MunicipalityListExpectedVotesControl.tsx,MunicipalityListTrendControl.tsx,src/components/campaign/leadership/LeadershipListSupportStatusControl.tsx— os três call sites de F1src/app/(campaign)/campanha/(app)/liderancas/support-status/route.ts,municipios/{political-trend,expected-votes,advisors,engagement-level}/route.ts— os cinco call sites de F2src/utilities/campaignJsonMutationRoute.ts,src/utilities/sameOriginRequest.ts— onde F2 pousaria- niveis-de-envolvimento.md (E14 ✓) — o 5º controle/rota, que disparou F2/F3 e F5;
src/components/campaign/municipality/MunicipalityListLevelControl.tsxé o call site de submit explícito na folha src/components/campaign/shared/CampaignCellEditOverlay.tsxesrc/components/campaign/municipality/MunicipalityListSignalControl.tsx— a casca de F4/F5 e o precedente de footer que ela ainda não expressa- AGENTS.md — abstrações precisam de 3+ call sites (aqui há exatamente 3 para F1, 5 para F2/F3)