Inline staff edits for advisors, political trend, and expected votes on /campanha/pracas; absorb post-simplify debts into A9+ and C8 plans.
11 KiB
Escala e DRY pós-A9 (loader da lista de Praças)
Status: registrado no roadmap (Fase 1 pendente; B7 entregue 2026-07-21 — prioridade sobe)
Atualizado em: 2026-07-21 (capture-review-debts pós-B7 + pós-B9 /simplify)
Item do roadmap: docs/roadmap.md (Trilha A, fill-in A9+ pós-A9)
Impeccable: A — N/A (sem superfície UI; otimização de loader)
Appetite: ~1–1,5 dia eng (F1 loader + F2 revalidate pós-B9; PR único ou dois commits)
Responsável: —
Contexto
O A9 (estimativa-votos-praca.md) entrega plaza.expectedVotes (staff-only), setPlazaExpectedVotes, fallback expectedVotes ?? effectiveTotal em mapa/overview/dashboard, UI em /editar + leitura na lista/detalhe, migration 20260721_133444_add_plaza_expected_votes, e helpers resolvePlazaStaffVoteTotal / rollupPlazaStaffVotes / sumStaffPledgeEffectiveTotal em votePledgeData.ts.
Uma passagem /simplify pós-entrega já limpou o que cabia em cleanup: form optionalIntegerFormValue único; remoção de hasStaffVoteData; StaffPlazaVotesDisplay compartilhado; JSDoc da métrica 2026; testes unit do rollup.
O revisor de performance marcou como maior que simplify o follow-up abaixo. Sem registro, cada abertura de /campanha/pracas (staff) dispara três agregações de pledges sobre conjuntos sobrepostos.
-
Query triplicada de pledges na página
/campanha/pracas.page.tsxchama em paraleloloadPlazaListPageData(pledges da página atual),loadPlazaListOverviewData(pledges de todo o conjunto filtrado) eloadPlazaMapBundle(pledges do conjunto filtrado do mapa — desde B7 o escopo seguebuildPlazaListWhere, não mais todas as Praças acessíveis). Cada loader ainda invocaaggregatePledgesByPlazade forma independente. -
Dois
findde Praças no mesmo filtro (overview + mapa). Ambos usambuildPlazaListWherecompagination: falseeselectdistinto — duplicação de round-trip por request quando o mapa está visível (staff, conjunto não vazio). -
Revalidação full-page após edição inline (B9). Cada save em
listFormActions.tschamarevalidatePath('/campanha/pracas', 'page')(+ detalhe), o que reroda overview unpaginado, mapa e lista — custo amplificado quando o coordenador edita várias células seguidas (pós-B9).
Já resolvido no simplify/critique (não reabrir): parsing duplo do form expectedVotes; hasStaffVoteData derivado de staffVoteTotal > 0; rollupPlazaStaffVotes + sumStaffPledgeEffectiveTotal; StaffPlazaVotesDisplay; assinatura estreita de resolvePlazaStaffVoteTotal; testes unit do rollup. Pós-B7 simplify: PlazaListSearchParams exportado de plazaUi.ts; parse único no map loader (loadScopedPlazas recebe PlazaListState).
Explicitamente fora (triage capture-review-debts 2026-07-21 pós-A9): semântica lista (só expectedVotes manual) vs mapa/overview (fallback) — decisão de produto A9; merge de forms Estratégia + Votos no /editar; grid cosmético do PlazaStrategyCard; loadPlazaPledges em abas distintas do detalhe (uma aba por request); débitos adiados/não escopo do plano A9 (nota/autor, chip auto-sugerir, histórico, filtro ?expectedVotes=); critique Impeccable formal por superfície → R6.
Explicitamente fora (triage capture-review-debts 2026-07-21 pós-B7): Promise.all nos loads TSE por ano em plazaMapData (micro-opt pré-existente; gatilho abaixo); testes int extras em plazaMapData (region/leader/compare) — cobertura opcional no próximo toque no loader; split do teste advisor por kind (legibilidade).
Explicitamente fora (triage capture-review-debts 2026-07-21 pós-B9): ~75 hooks useActionState por página (3 controles × 25 linhas × 2 views) — gatilho: reclamação de perf ou R6; merge listFormActions ↔ /editar → C8 F4; hook popover compartilhado / layout responsivo único / lazy advisor options → gatilhos no plano B9.
Objetivos
- Abrir
/campanha/pracascom filtro amplo não executa trêsaggregatePledgesByPlazaindependentes quando um mapa de agregados compartilhado basta. - Overview, mapa 2026 e coluna da página reutilizam o mesmo
Map<plazaId, PlazaPledgeAggregate>(e, onde os filtros coincidirem, o mesmofindde Praças). - Saves inline da lista (B9) não disparam rerender full-page desnecessário quando um refresh parcial (segmento de lista, tag de cache, ou
revalidatePathestreito) preserva paridade de KPIs/mapa. - Paridade funcional: KPIs, métrica 2026 e sublinha “Nas lideranças” permanecem idênticos ao comportamento pós-A9.
- Guardrails: sem migration, sem collection, sem Consent, sem server action nova; access inalterado (
overrideAccess: falsenos reads de Praça; agregado de pledges continua admin-bypass intencional com ids já access-checked).
Decisões travadas
- Um fill-in A9+, uma fase (F1). Mesmo racional de A7/C6/A8+: um slug de plano, PR único. Rejeitado: item de roadmap separado
A10— follow-up pós-entrega, não feature nova. - Dependência dura de A9. Só faz sentido com
expectedVotes,rollupPlazaStaffVotese os três loaders já no produto; não reabre escopo de schema ou UI de edição. - F1 não remove overview nem mapa. Otimiza como os dados chegam; paridade com a plano A9 permanece. Rejeitado: unificar lista+overview num único
findunpaginado sem validar regressão de paginação/depth. - Cortável se a lista com mapa permanecer aceitável em campo com dezenas de assessores; menos cortável desde B7 entregue (mapa filtrado + sempre visível para staff amplifica o custo do triplo agregado quando o filtro é amplo).
- i18n e naming (AGENTS.md): identificadores em inglês (
loadPlazaListPageBundle,PlazaListPledgeAggregates); strings visíveis inalteradas em pt-BR.
Questões em aberto
- Bundle único vs compartilhar só o mapa de pledges? Opções: (A)
loadPlazaListPageBundleretorna{ list, overview, mapInputs, pledgeAggregates }; (B) só deduplicaraggregatePledgesByPlazanum helperloadPlazaPledgeAggregatesForListPageconsumido pelos três loaders. Recomendação: (A) se os trêsfindde Praças puderem compartilhar escopo sem duplicar lógica de filtro; senão (B) como primeiro passo — ganho imediato no hot path de pledges. - Overview unpaginado vs página paginada? Recomendação: manter dois
findde Praças (conjunto filtrado inteiro vs página) — o gargalo registrado é o terceiro agregado de pledges, não a paginação em si; unificarfindsó se profiling mostrar custo dominante em Praças, não em pledges.
Abordagem proposta
flowchart TD
A9["A9 expectedVotes ✓"] --> F1
B9["B9 edição inline lista"] --> F2
F1["Fase 1 — loadPlazaListPageBundle<br/>1× aggregatePledgesByPlaza"]
F2["Fase 2 — revalidate escopado<br/>pós-save inline"]
F1 --> List["PlazaList página"]
F1 --> Overview["PlazaListOverview KPIs"]
F1 --> Map["PlazaMapBundle 2026"]
B7["B7 mapa filtrado ✓"] -.mesmo bundle.-> F1
F2 -.menos rerender.-> List
Fase 1 — Loader compartilhado da lista de Praças
- Introduzir
loadPlazaListPageBundle(ou equivalente emplazaPageData.ts+ ajuste fino emplazaMapData.ts) que:- Resolve filtros uma vez (
parsePlazaListParams/buildPlazaListWhere). - Carrega Praças do escopo necessário (página + overview + mapa) com o mínimo de round-trips.
- Chama
aggregatePledgesByPlazauma vez sobre a união de ids necessários (ou sobre o conjunto filtrado inteiro se mais simples e dentro do appetite). - Expõe
pledgeAggregatesreutilizado portoPlazaListViewModel,rollupPlazaStaffVoteseloadPlazaMapBundle(refatorar para aceitar agregados pré-computados ou extrair helper puro).
- Resolve filtros uma vez (
- Atualizar
src/app/(campaign)/campanha/(app)/pracas/page.tsxpara consumir o bundle. - Testes: int ou unit do bundle — paridade de
staffVoteTotale métrica 2026 antes/depois; advisor scope inalterado.
Fase 2 — Revalidação escopada pós-B9
- Avaliar
revalidatePathestreito (só segmento necessário) ou tag de cache dedicada à lista vs full-pagerevalidatePath('/campanha/pracas', 'page')emlistFormActions.ts. - Critério de aceite: após N saves inline seguidos, overview/mapa/lista permanecem corretos sem rerodar loaders caros quando o dado alterado não afeta KPI agregado (ex.: tendência não muda métrica 2026 — validar caso a caso).
- Coordenar com C8 F4 se extrair
revalidatePlazaListPathscompartilhado entre lista e/editar. - Testes: int leve ou e2e smoke de save inline + paridade visual de KPIs (manual ok se appetite apertar).
Migration: nenhuma.
Dependências
- Dura: A9 estimativa-votos-praca.md — campo, agregadores e superfícies (merge em
main). - Suave: B7 mapa-pracas-filtrado.md — entregue 2026-07-21; mesmo URL de filtro; F1 deduplica pledges e pode compartilhar parse/
findonde os escopos coincidem. - Suave: B9 edicao-rapida-lista-pracas.md — F2 só faz sentido com saves inline na lista; não reabre escopo de UI B9.
- Reusa:
aggregatePledgesByPlaza,rollupPlazaStaffVotes,resolvePlazaStaffVoteTotal, precedente E6 F1 em escala-dry-pos-e1.md.
Não escopo
- SQL aggregate de pledges (
COUNT(*) FILTER) — volume ainda baixo; reavaliar no 3º hot path ou com evidência de latency. - Unificar
loadPlazaPledgesentre abas Overview/Lideranças no detalhe — defer (uma aba por request). - Implementar os controles inline da lista → B9 (entregue em código; polish Impeccable → R6).
- Merge de forms no
/editar— fora do triage. - Impeccable critique das superfícies A9 → R6.
Rabbit holes
- Unificar lista+overview+mapa num único
findunpaginado de 436 Praças sempre. Mitigação: F1 foca em deduplicar pledges;findde Praças permanece paginado onde já é. - Cache cross-request de agregados. Mitigação: bundle por request RSC apenas; sem Redis/memória global neste fill-in.
Adiado com gatilho
- SQL aggregate espelhando
buildPlazaListWhere. Revisitar quando profiling mostraraggregatePledgesByPlazadominando TTFB com filtros amplos + mapa sempre montado. - Compartilhar bundle com dashboard geral. Revisitar se o dashboard passar a carregar mapa+lista na mesma rota.
- Loads TSE sequenciais por ano em
loadPlazaMapBundle. Revisitar comPromise.allsó se profiling com?compare=mostrar latência dominante (pré-existente; fora do escopo A9+).
Referências
docs/roadmap.md(Trilha A, A9 entregue + fill-in A9+)docs/plans/estimativa-votos-praca.md— plano pai A9docs/plans/escala-dry-pos-e1.md— precedente E6 F1 (lista+overview núcleos)src/app/(campaign)/campanha/(app)/pracas/page.tsx—Promise.alldos três loaderssrc/app/(campaign)/campanha/(app)/pracas/listFormActions.ts—revalidatePlazaListPathspós-B9src/utilities/plazaPageData.ts—loadPlazaListPageData,loadPlazaListOverviewDatasrc/utilities/plazaMapData.ts—loadPlazaMapBundle, métrica 2026src/utilities/votePledgeData.ts—aggregatePledgesByPlaza,rollupPlazaStaffVotes- AGENTS.md — naming EN/pt-BR; access staff; sem PII