9.7 KiB
Impl: C89 — Página Atualizações: feed de cards + filtro + criar (modal / bottom sheet)
Status: em execução Atualizado em: 2026-08-08 (aprovado em gate humano 2026-08-08; execução concluída) Issue: #401 Intenção: docs/plans/feed-atualizacoes-campanha-threads.md Appetite: herdado ~1,5–2 dias eng — cabe (1 página + 1 modal + 1 action + loaders, sem migration)
Leitura da intenção
- Outcome:
/campanha/atualizacoesdeixa de ser placeholder e vira um feed operacional da carteira do ator (staff), mais recentes no topo, com filtro combobox (município, polaridade, urgente, quem criou, texto) e criação in-place ("+": modal desktop / bottom sheet mobile) reusando o registro unificado já vivo (C87) — sem reload de página à toa. - O que NÃO negociar: leader lockdown (gate
staff); assessor só nos municípios que administra (access existente, fail-closed); card é leitura em v1 (sem thread — C88); criar segue o formulário unificado, não um segundo modelo; p/adversarySignalsó staff (coordinator/advisor/candidate). - O que reavaliar: não existe "dashboard últimas atualizações de campo" no
código — o precedente real do feed é o
UpdatesTabdo detalhe de município (MunicipalityDetailTabs+loadMunicipalityUpdatesFeed). A direção da intenção continua correta, mas o "precedente a olhar" apontava para um painel que não existe.
Abordagem recomendada
flowchart LR
A[atualizacoes/page.tsx server] --> B[requireCampaignPageActor staff]
A --> C[resolveFeedUrl + loadCampaignUpdatesFeed]
C --> D[CampaignUpdatesFilters omnibox + envio]
C --> E[CampaignUpdatesFeed cards]
D --> F["+ abre CreateModal (Dialog desktop / Drawer mobile)"]
F --> G[form action createCampaignUpdatesFormAction]
G --> A
Opções consideradas: A (novos módulos de URL/omnibox/feed espelhando o split
de municipios) | B (tudo dentro de municipalityUpdatePageData.ts) | C (pasta
nova utilities/updates/)
Recomendação: A — espelhar o split de municipios (*ListUrl +
*Omnibox + *PageData), que é o canonical do repo; mantém o contrato de URL
congelável (B18 saved filters) e o page-data por-município intacto.
Rejeitadas: B porque mistura leitura por-município e feed da carteira no
mesmo módulo; C porque uma pasta nova para uma página é premature.
Componentes / mudanças
municipalityUpdateListUrl.ts(src/utilities/municipality/): estado do feed —page,q?(busca de texto),slugs?(município),polarities?(boa|neutra|ruim, "todas"→ausente,parseExhaustiveEnumParam),urgent?(exclusivo),authors?(ids de campaignUser). Parse/serialize canônicos viacampaignListUrl(resolveListUrl,buildListHref,strictDecimalInteger,normalizedText),buildCampaignUpdatesWhere(state)→Where(body contains / municipality in / polarity in / urgent equals / author in eand),buildCampaignUpdatesHref(base/campanha/atualizacoes).municipalityUpdateOmnibox.ts(src/utilities/municipality/): adapter fiel amunicipalityOmnibox— chips (Busca/Município/Polaridade/Urgente/Autor), seeds agrupados (Município, Polaridade, Urgente, Autor, Busca), apply/remove/ clear,withPageReset. ReusamunicipalityFilterOptionsForSlugs(label viamunicipalityCatalog).campaignUpdatesFeedData.ts(src/utilities/municipality/): novo view model do card (id, body, polarity, urgent, adversarySignal, createdAt, authorName, authorAvatarUrl, municipalitySlug+Name) e:loadCampaignUpdatesFeed(payload, user, state)—payload.findemmunicipalityUpdatesort:-createdAt,depth:0,user,overrideAccess:false, sem cláusula de município: o accesscanReadMunicipalityUpdate(scoped-read) já restringe à carteira do assessor. Pós-processa nomes/avatars (novoloadCampaignUserDisplayByIds) e rótulos de município (loadMunicipalityLabelsByIds).loadCampaignUpdatesFeedFacets(payload, user)— slugs de municípios da carteira (unrestricted → todos do catálogo; advisor →getAccessibleMunicipalityIds→ slugs) e autores presentes na carteira (find seletivoauthor,limit:0, rotulado porloadCampaignUserNamesByIds).
loadCampaignUserDisplayByIds(src/utilities/loadNamesByIds.ts): extensão do "resolve names" — id →{ name, avatarUrl }(depth 1 +select:{name:true, avatar:true},mediaDocumentUrl). Dono certo: o módulo de resolução de nomes; mantémloadCampaignUserNamesByIdsintacto.CampaignUpdatesFeed.tsx(+ card): feed de cards responsivo. Card:CampaignUserAvatarno canto superior esquerdo, body, badges polaridade/ urgente/adversário (variants já usadas emMunicipalityUpdateFeed), rodapé autor + município + data (Intl.DateTimeFormatpt-BR). Card é só leitura (sem link/thread — C88).CampaignUpdatesFilters.tsx(client):CampaignListOmnibox+ trailingButton"+ Nova atualização";useCampaignListFilterNavigation+CampaignListPendingBoundary/CampaignListResults(mesmo esqueleto de transição de municípios).CampaignUpdatesCreateModal.tsx(client): híbridoDialog(desktop)/Drawer(mobile) viauseIsMobile— precedenteCampaignQuickActionsOverlay; corpo = combobox de município (StrictComboboxsobre slugs acessíveis, label via catálogo) +MunicipalityUpdateFields(reuso do form unificado C87) +useActionState.createFormActions.ts(atualizacoes/): action fina —runCampaignFormAction→ parse →createMunicipalityUpdate→revalidatePath('/campanha/atualizacoes'). Extrai o parse deupdateFormActions.tspara um helper compartilhado (parseMunicipalityUpdateForm(formData)) — 2º call site, DRY ganha.atualizacoes/page.tsx: substitui o placeholder;resolveCampaignUpdatesUrl(+redirect canônico),gate:'staff', feed + facetas + footer (CampaignListFootercom total/página).- Migration: nenhuma — filtros todos em campos já indexados
(
municipality,author,polarity,urgentjá têm index). - Access / Consent: nenhum novo. Reuso total de
canReadMunicipalityUpdate(scoped-read) ecreateMunicipalityUpdate(transação +adversarySignalstaff-only viaisCampaignStaff). Leader não alcança a página (gate staff).
Dados → forma (se aplicável)
Feed operacional cronológico: cards, mais recentes no topo, sem agregação estadual — leitura relativa à carteira (restrição da intenção). Sem % absoluto.
Fases verificáveis
- Tracer / pure (server):
municipalityUpdateListUrl+municipalityUpdateOmnibox- unit specs (canonicalização, "todas polaridades→ausente", page clamp,
chips/sugestões/apply/remove) —
pnpm gate:fast.
- unit specs (canonicalização, "todas polaridades→ausente", page clamp,
chips/sugestões/apply/remove) —
- Loader + view model:
campaignUpdatesFeedData+loadCampaignUserDisplayByIds; verificação por int spec leve do loader (carteira de advisor) se existir precedente análogo — senão unit puro. - UI: card feed → filtros (omnibox + "+") → modal/sheet + form → page. Impeccable D: shape → craft → critique → polish.
- Gates:
pnpm gate:fastna iteração;pnpm pushna entrega; e2e do fluxo criar+filtro se a suíte cobrir/campanha(verificar).
Rabbit holes / Não escopo (engenharia)
- 2º formulário de criação — cortado:
MunicipalityUpdateFields+ combobox de município, mesma action de escritura. - Busca de texto em autor/município — cortado:
qcobrebodysó; gatilho de revisita se o usuário pedir busca ampla. - Thread/card navegável — C88; card read-only.
- Analytics / scroll infinito / KPI — não escopo da intenção.
- Saved filters (B18) — não desta fatia; o contrato de URL já fica canônico para servir de base.
Adiado com gatilho (triage 2026-08-08)
- Promover
parseSlugsParam/parseAuthorsParamparacampaignListUrl(gémeos dos helpers privados domunicipalityListUrl; DRY 2 call sites). Gatilho: "quando um 3º*ListUrlprecisar do mesmo parse de slugs/ids". - Descartados (cheap_polish):
isStaffconstante na rota; copy do empty-state em função de filtro ativo;loading.tsxda rota;revalidatePathno-op; dedup manual pré-existente nomunicipalityUpdatePageData.
Riscos e mitigação
containsemtextarea(body): campo text no Postgres; mesmo caret dename:{contains}das listas — verificar num int/unit dowhere.- Feed com access por carteira:
overrideAccess:false+useré o mesmo caminho doUpdatesTab; facets de autor/município usam o canal admin justificado (ids já autorizados / slugs da carteira). - Modal + server action:
revalidatePath('/campanha/atualizacoes')explícito na action para o card novo subir ao topo; estado de filtro preservado (searchParams intactos). Achado real (2026-08-08): o modal de criação não pode ser filho React do<form role="search">dos filtros — o React 19 não liga progressive enhancement ($ACTION_ID) num action-form aninhado em outro<form>na árvore de componentes (nenhum POST disparava; verificado em dev E build de produção). Fix: o modal é irmão do form de filtros (wrap em<div>,CampaignUpdatesFilters.tsx). - 435 municípios no combobox: client-side, slugs→catálogo (padrão B16+);
StrictComboboxfiltra no word-start — sem carga no servidor.
Aceite de engenharia
- Aceite de produto da intenção coberto (feed + filtro 5 dimensões + criar modal/sheet)
- Invariantes AGENTS/engineering-standards (gate staff, access fail-closed, form unificado)
- Testes de domínio previstos (unit URL/omnibox; loader leve)
- Sem migration;
generate:importmapse novo componente client (colocar emcomponents.jsonse necessário)