teqo/docs/plans/escala-dry-pos-b32.md
Francisco Ignácio Fontoura Solla 93b58a9b3c Register the E14 closing triage on B32+.
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.
2026-07-27 22:24:34 -03:00

20 KiB
Raw Blame History

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 }), faz cast da resposta, reverte para o valor confirmado em erro/exceção, atualiza committed<X>Ref em sucesso — sempre guardado por generation !== saveGenerationRef.current.
  • scheduleSave/handleXChange: marca isDirty, atualiza o rascunho local, reagenda o setTimeout.
  • 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 /simplify da própria entrega, espelhando o flushDraft que o B24 já tinha.
  • statusMessage calculado 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 (guardCampaignJsonMutationRequest ou nome equivalente) que combina isSameOriginRequest + parseCampaignJsonRequestBody nos 5 route.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 fetch cliente (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 o toast.error do 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.md já corrigiu uma página com três regiões vivas competindo, e a cura não pode reintroduzir isso.
  • F5 (slot footer + formId na 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, CampaignCellEditOverlay fixa um DrawerFooter com "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 é o MunicipalityListSignalControl, que mantém container próprio justamente para pôr o submit no DrawerFooter com "Cancelar" ao lado. Escopo: slot opcional footer (mais formId, para o submit viver fora do <form> por HTML padrão), o controle do E14 e o Sinal como call sites, e um caso em campaignCellEditOverlay.unit.spec.ts pinando que a folha com footer não renderiza o "Fechar" default. Só o variant="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 por TValue vs. par de callbacks equals/buildRequest/parseResponse — fica para a implementação, com o mesmo filtro que o B33+ aplicou ao toHref).
  • 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 inFlightTrendRef do B24 (dedup de blur+close) ou deixar esse guard como responsabilidade do chamador? Opções: (a) o hook expõe um flush() 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 (o onBlur do textarea e o handleOpenChange); um hook com flush() ú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&lt;TValue&gt;<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 recebe parseResponse como callback, mesmo padrão de useCampaignListFilterNavigation (recebe toHref, nunca importa os módulos de URL por domínio).
  • F2 — guardCampaignJsonMutationRequest(request, schema) (se aprovado): retorna { ok: true, body } | { ok: false, response }, combinando isSameOriginRequest + parseCampaignJsonRequestBody + bodySchema.parse num só call site por rota. Vive ao lado de campaignJsonMutationErrorResponse em src/utilities/campaignJsonMutationRoute.ts.
  • F3 — postCampaignJson<TResponse>(url, body, signal) (se aprovado): fetch com 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 com requestSeqRef/latestConfirmedRef, genuinamente diferente do debounce single-value; participa só de F2/F3 (preâmbulo de rota/fetch), nunca de F1.
  • Migrar SupporterFilters/ActivityFilters ou 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 TValue totalmente genérico com deepEqual embutido." Um deepEqual genérico reabre a discussão que voteEstimatesEqual/trendsEqual/=== já resolveram por domínio (cada um sabe o que "igual" significa para o seu shape — ex. trendsEqual normaliza a nota antes de comparar). Mitigação neste item: equals continua 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.md já 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.
  • MunicipalityListAdvisorsControl adotar 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ó o fetch+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á em shared/ e já parametrizada por um record de COPY, servindo as duas direções da relação) e MunicipalityListAdvisorsControl.tsx (B27 ✓) repetem o mesmo corpo string por string — w-80 p-0, header relative flex flex-col gap-2 p-3 pb-0, Spinner, linha de chips flex flex-wrap gap-1.5 px-3 pt-2, o Badge de remover (max-w-full cursor-pointer gap-1 pr-1 font-normal hover:bg-destructive/15), Command shouldFilter={false} e a linha vazia px-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 em shared/, 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 introduziu reportFailure nos 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 F1
  • src/app/(campaign)/campanha/(app)/liderancas/support-status/route.ts, municipios/{political-trend,expected-votes,advisors,engagement-level}/route.ts — os cinco call sites de F2
  • src/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.tsx e src/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)