teqo/docs/plans/edicao-rapida-lista-pracas.md
Francisco Ignácio Fontoura Solla adc0f31f5b Sync all project docs with the deployed remodel and hardening; compile roadmap
- Compile docs/roadmap.md into a next-steps document (277→206 lines): R0–R5/M1–M5
  tables and the delivered map/list item paragraphs compressed into 'Já entregue';
  janelas, grafo and cortes list only open IDs; C10/C11/C8 fill-ins keep their
  original triggers; C5 moved under 'A validar'.
- Record the production deploy of the destructive remodel chain (2026-07-23 Vercel
  builds) across roadmap, AGENTS.md, the project notebook and plans — supersedes
  every 'deploy pendente'; smoke pós-deploy + onboarding remain the open blockers.
- Fix AGENTS.md internal contradictions: Município locked-decisions bullet (435,
  Camaçari whole, candidate role), campaignUser role enum, deploy-checklist item 7
  as historical, access/* structure note, election-aggregates artifact +
  election-tse revalidate runbook.
- Sync open plans to real identifiers (plaza*/nucleus* → municipality*): the
  intelligence program (master + E8–E15/B13/C12 with artifact/caching context and
  satisfied deps), B8 rescoped to Salvador ZE 1–19 only, WhatsApp D3–D5, D2, A6
  (now the insight layer over stateDeputy), RS+, onda-0 smoke step.
- Close items verified done in code: C8 F4 (DRY de forms) complete, filtros-auto
  shared pending shell, petition generateStaticParams select/depth; ledger the
  surviving user-visible 'Praça' copy in src as new P2 debt.
- Banner delivered praça-era plans (production note + rename pointer); mark
  remodelagem-pracas.md superseded and remodelagem-municipios.md delivered.
- TECH-DEBT smell statuses, TESTING RBAC row, README quality gates, campanha
  UI rules updated to current component names.
2026-07-24 02:04:45 -03:00

9.1 KiB
Raw Blame History

Edição rápida na lista de Praças

Nota (2026-07-24): entregue na era Praças e em produção desde 2026-07-23. A remodelagem M1 renomeou os identificadores plaza* → municipality* e as rotas pracas/ → municipios/; os nomes neste plano são os da época. Nomes atuais: ver remodelagem-municipios.md.

Status: entregue 2026-07-21 (em produção desde 2026-07-23) Atualizado em: 2026-07-21 Item do roadmap: docs/roadmap.md (Trilha B, item B9 — entregue 2026-07-21) Impeccable: B — encaixe em PlazaList / cards mobile em /campanha/pracas (sem rota nova) Appetite: ~1–1,5 dia eng; 3 affordances na linha + reuso de actions (A9 + plaza); sem migration própria Responsável: —

Revisão 2026-07-21 (pós-implementação + /simplify): PlazaList*Control + plazaStaffFormActions; coluna Tendência; PlazaAdvisorAvatarStack. Débitos pós-B9 absorvidos em A9+ F2 / C8 F4 (entregues).

Design (Impeccable)

Âncoras: PRODUCT.md / DESIGN.md (register product — Field Desk) · tema data-theme='campaign' · shells CampaignPageShell, PlazaList, shadcn Table/Popover/NativeSelect/Input.

Na implementação (implement-roadmap-item): craft compacto → critique → polish (sem shape longo — interação em tabela existente).

Brief compacto:

  • Persona / contexto: Alex (Coordenador Geral / Assessor) na lista de 436 Praças sob pressão de convenções — precisa designar assessoria, marcar conjuntura e lançar o total esperado da Praça sem abrir N páginas /editar.
  • Job principal: editar Assessores, Tendência e Votos estimados (total da Praça) sem sair da lista, com refresh RSC após save.
  • Estratégia de cor: Restrained (inalterada).
  • Anti-goals: planilha editável full-row; data-grid genérico; Sheet de pledges como substituto do total da Praça; bulk multi-select neste item.

Contexto

Em /campanha/pracas, PlazaList é somente leitura. Com A9 entregue, a coluna “Votos estimados” mostra plaza.expectedVotes (total esperado staff-only), com a soma de votePledge como cobertura secundária (“Nas lideranças”). Tendência já filtra (?trend=) mas ainda não aparece na tabela.

Edição hoje exige /campanha/pracas/[slug]/editar (assessores, tendência, expectedVotes via A9) ou o detalhe para pledges por liderança.

Pedido de produto (2026-07-21): edição rápida na tabela de Assessores, Votos estimados e Tendência. Correção de modelo (2026-07-21): Votos estimados = total da Praça (A9), não o agregado de lideranças — por isso B9 depende de A9.

Objetivos

  • Staff edita na linha: Assessores (só Coordenador Geral), Tendência (favoravel|neutra|desfavoravel + limpar) e Votos estimados (expectedVotes — input numérico direto na coluna / popover curto).
  • Coluna Tendência visível na tabela/cards staff.
  • Coluna Votos estimados edita expectedVotes (action A9); a cobertura “Nas lideranças” permanece read-only na lista (edição de pledges continua no detalhe da Praça).
  • Access idêntico às actions existentes.
  • Guardrails: sem migration neste item (A9); sem Consent; leader sem colunas staff.

Decisões travadas

  • Item B9 na trilha B; dependência dura de A9. Sem expectedVotes a coluna não tem o que editar. (Usuário, 2026-07-21.) Rejeitado: B9 só com Sheet de pledges (plano anterior); fundir A9+B9 num único ID (mistura schema caro com UI).
  • Coluna “Votos estimados” = edição direta de expectedVotes. Popover/campo numérico + salvar (ou blur+Enter); reusa setPlazaExpectedVotes. Rejeitado: Sheet de pledges como affordance principal da coluna; editar voteGoals no lugar.
  • Pledges fora do affordance da coluna. Cobertura “Nas lideranças” é informativa; deep-link “Abrir Praça” para CRM pessoa a pessoa. Rejeitado: dois editores na mesma célula (confunde total vs cobertura).
  • Padrão UX: Popover por célula (não contentEditable em massa). Tendência = select; Assessores = checkboxes; Votos = number input. Touch min-h-11. Rejeitado: inputs sempre montados em todas as linhas.
  • Tendência v1 = status only; nota no /editar. Rejeitado: nota obrigatória na lista.
  • Assessores: reusar assignPlazaAdvisors. Coordenador-only. Rejeitado: bulk multi-Praça neste item.
  • i18n e naming (AGENTS.md): PlazaListTrendControl, PlazaListAdvisorsControl, PlazaListExpectedVotesControl; strings pt-BR.

Questões em aberto

  • Salvar votos no blur, Enter ou botão explícito? Opções: A) Enter + botão | B) debounce blur | C) só botão. Recomendação: A — evita gravação acidental em scroll mobile; alinhado a forms Field Desk.
  • Carregar opções de assessor na página ou sob demanda? Opções: A) SSR staff | B) action ao abrir. Recomendação: A se o conjunto for pequeno; default A (assumido — validar no craft).
  • Refresh: padrão revalidatePath / RSC refresh dos formActions da Praça.

Abordagem proposta

flowchart LR
  list["PlazaList row"] --> trend["Popover/Select tendência"]
  list --> advisors["Popover assessores"]
  list --> votes["Input expectedVotes"]
  trend --> a1["setPlazaPoliticalTrend"]
  advisors --> a2["assignPlazaAdvisors"]
  votes --> a3["setPlazaExpectedVotes"]
  a1 --> refresh["RSC refresh lista"]
  a2 --> refresh
  a3 --> refresh

Componentes:

  • PlazaList: coluna Tendência; células Assessores / Votos estimados / Tendência = gatilhos staff; cobertura de pledges read-only; cards mobile espelham. Leader inalterado.
  • PlazaListTrendControl: select status → setPlazaPoliticalTrend (A9 já deve ter politicalTrend.status no list select se B9 precisar — senão incluir aqui).
  • PlazaListAdvisorsControl: Popover checkboxes como PlazaAdvisorsForm; só coordinator.
  • PlazaListExpectedVotesControl: input do total → setPlazaExpectedVotes (A9). Mostra “—” quando null; após save, refresh.
  • Form actions thin em pracas/: wrappers das actions em actions/plaza.ts.
  • Depth check: sem plazaQuickEditService; sem editable-cell genérico (<3 call sites).
  • Migration: nenhuma (A9).
  • Testes: access (advisor não assign; leader sem controles); int/e2e leve de update expectedVotes pela lista.

Dependências

  • Dura: A9 (estimativa-votos-praca.md) — campo + action setPlazaExpectedVotes.
  • Dura: R2 — entregue (transitiva via A9).
  • Suave: R6; fill-in filtros-auto-pracas.md.
  • Reusa: assignPlazaAdvisors / setPlazaPoliticalTrend / setPlazaExpectedVotes, PlazaAdvisorsForm, plazaViewModels, campaignAccess.

Não escopo

  • Schema expectedVotes / mapa fallback → A9.
  • Edição de pledges por liderança na lista; metas (voteGoals); nota de tendência; bulk assign.
  • B7 mapa filtrado; B8 polígonos; Pixel Meta.

Rabbit holes

  • Data-grid / spreadsheet mode. Mitigação: três affordances nomeadas.
  • Optimistic UI do total. Mitigação: save → refresh servidor.
  • Reabrir Sheet de pledges “só para completar”. Mitigação: fora de escopo explícito; detalhe da Praça.

Adiado com gatilho

  • Nota de tendência no popover. Feedback de uso.
  • Bulk assign de assessor a N Praças. Volume real na fila “Sem assessor”.
  • Atalho “ajustar lideranças” a partir da cobertura. Se assessores pedirem sem abrir a Praça.
  • Hook/shell popover compartilhado (usePlazaListPopoverForm). Gatilho: 4º inline editor na campanha.
  • PlazaAdvisorCheckboxList extraído de PlazaAdvisorsForm. Gatilho: 3º uso ou refactor do form /editar.
  • Layout responsivo único (uma árvore React vs mobile+desktop duplicados). Gatilho: page size >25 ou profiling de hydration.
  • ~75 hooks useActionState por página. Gatilho: reclamação de perf ou R6.
  • E2E save inline na lista. Gatilho: smoke pós-merge B9.

Simplify (2026-07-21)

Limpezas aplicadas no cleanup da sessão (não reabrir): politicalTrend.note via hidden field (sem findByID extra); politicalTrendBadgeVariant em plazaUi.ts; PlazaAdvisorAvatarStack; tipos PoliticalTrendStatus; max={1_000_000} no input; higiene de testes.

Débitos absorvidos noutros planos: twin listFormActions ↔ /editar → C8 F4 entregue (escala-dry-pos-c6.md: plazaStaffFormActions.ts). revalidatePath full-page pós-save → A9+ F2 entregue (escala-dry-pos-a9.md: plazaRevalidation.ts + plazaSlug).

Explicitamente fora (triage): lazy-load getEligibleAdvisorOptions; PopoverAnchor não usado; helper parsePoliticalTrendStatus; unit tests dos PlazaList*Control.

Referências

  • docs/roadmap.md (Trilha B / B9; depende de A9)
  • docs/plans/estimativa-votos-praca.md — modelo + action
  • src/components/campaign/PlazaList.tsx — superfície alvo
  • src/app/(campaign)/campanha/(app)/pracas/page.tsx
  • src/app/(campaign)/campanha/actions/plaza.ts
  • src/utilities/plazaViewModels.ts
  • AGENTS.md — Campaign auth, naming, overrideAccess
  • PRODUCT.md / DESIGN.md — Field Desk