teqo-backup/docs/plans/feed-atualizacoes-campanha-threads-impl.md
2026-08-08 23:11:05 -03:00

9.7 KiB
Raw Blame History

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/atualizacoes deixa 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/ adversarySignal só 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 UpdatesTab do 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 via campaignListUrl (resolveListUrl, buildListHref, strictDecimalInteger, normalizedText), buildCampaignUpdatesWhere(state) → Where (body contains / municipality in / polarity in / urgent equals / author in e and), buildCampaignUpdatesHref (base /campanha/atualizacoes).
  • municipalityUpdateOmnibox.ts (src/utilities/municipality/): adapter fiel a municipalityOmnibox — chips (Busca/Município/Polaridade/Urgente/Autor), seeds agrupados (Município, Polaridade, Urgente, Autor, Busca), apply/remove/ clear, withPageReset. Reusa municipalityFilterOptionsForSlugs (label via municipalityCatalog).
  • 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.find em municipalityUpdate sort:-createdAt, depth:0, user, overrideAccess:false, sem cláusula de município: o access canReadMunicipalityUpdate (scoped-read) já restringe à carteira do assessor. Pós-processa nomes/avatars (novo loadCampaignUserDisplayByIds) 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 seletivo author, limit:0, rotulado por loadCampaignUserNamesByIds).
  • 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ém loadCampaignUserNamesByIds intacto.
  • CampaignUpdatesFeed.tsx (+ card): feed de cards responsivo. Card: CampaignUserAvatar no canto superior esquerdo, body, badges polaridade/ urgente/adversário (variants já usadas em MunicipalityUpdateFeed), rodapé autor + município + data (Intl.DateTimeFormat pt-BR). Card é só leitura (sem link/thread — C88).
  • CampaignUpdatesFilters.tsx (client): CampaignListOmnibox + trailing Button "+ Nova atualização"; useCampaignListFilterNavigation + CampaignListPendingBoundary/CampaignListResults (mesmo esqueleto de transição de municípios).
  • CampaignUpdatesCreateModal.tsx (client): híbrido Dialog(desktop)/Drawer(mobile) via useIsMobile — precedente CampaignQuickActionsOverlay; corpo = combobox de município (StrictCombobox sobre 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 de updateFormActions.ts para 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 (CampaignListFooter com total/página).
  • Migration: nenhuma — filtros todos em campos já indexados (municipality, author, polarity, urgent já têm index).
  • Access / Consent: nenhum novo. Reuso total de canReadMunicipalityUpdate (scoped-read) e createMunicipalityUpdate (transação + adversarySignal staff-only via isCampaignStaff). 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

  1. Tracer / pure (server): municipalityUpdateListUrl + municipalityUpdateOmnibox
    • unit specs (canonicalização, "todas polaridades→ausente", page clamp, chips/sugestões/apply/remove) — pnpm gate:fast.
  2. 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.
  3. UI: card feed → filtros (omnibox + "+") → modal/sheet + form → page. Impeccable D: shape → craft → critique → polish.
  4. Gates: pnpm gate:fast na iteração; pnpm push na 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: q cobre body só; 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/parseAuthorsParam para campaignListUrl (gémeos dos helpers privados do municipalityListUrl; DRY 2 call sites). Gatilho: "quando um 3º *ListUrl precisar do mesmo parse de slugs/ids".
  • Descartados (cheap_polish): isStaff constante na rota; copy do empty-state em função de filtro ativo; loading.tsx da rota; revalidatePath no-op; dedup manual pré-existente no municipalityUpdatePageData.

Riscos e mitigação

  • contains em textarea (body): campo text no Postgres; mesmo caret de name:{contains} das listas — verificar num int/unit do where.
  • Feed com access por carteira: overrideAccess:false + user é o mesmo caminho do UpdatesTab; 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+); StrictCombobox filtra 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:importmap se novo componente client (colocar em components.json se necessário)