Issue #390 — entrada operacional staff com FullCalendar v7 route-local (semana/mês/lista), filtros compartilháveis por município/deputado/tag, criação pelo slot, detalhe por URL e remarcação drag/resize sob RBAC, transação e lock por atividade. - /campanha/atividades e giros permanecem como lista/fluxos legados - Sem migration/collection nova; reutiliza activity de C14 - Fuso Bahia, range exclusivo, erro/revert, loading/empty testados - Leader negado, advisor limitado pelo access atual - E2E cobre filtros, drag, mobile 390x844 e slot prefill - Int specs cobrem RBAC, concorrência e defense-in-depth Impl: docs/plans/fullcalendar-agenda-campanha-impl.md
17 KiB
Impl: FullCalendar em /campanha/agenda
Status: aprovado Atualizado em: 2026-08-07 Issue: #390 Intenção: docs/plans/fullcalendar-agenda-campanha.md Appetite restante: ~1,5–2 dias eng (herdado; sem ampliar para sync, recorrência ou taxonomia)
Leitura da intenção
- Outcome: staff opera a semana em
/campanha/agenda: filtra o recorte que pode ver, cria pelo slot, abre o detalhe e remarca compromissos permitidos. Semana é a vista inicial; mês e lista continuam a um clique. - O que NÃO negociar: filtros por município, deputado presente e tag; município obrigatório; coordinator/candidate são os únicos que remarcam compromisso com deputado; advisor preserva o escopo de atividades atual; leader continua em lockdown; C16 fica dona de import/sync.
- O que reavaliar: a hipótese previa novos componentes/actions de agenda sem saber que C14 já consolidou
activity, filtros, formulário e o gate no owner atual. Também deixava redirect das rotas antigas em aberto, mas giros ainda geram atividades semstartAt, que não cabem no FullCalendar.
Abordagem recomendada
flowchart LR
U[URL /campanha/agenda<br/>municipality + deputyPresent + tag] --> R[RSC staff-gated<br/>opções acessíveis]
R --> C[Ilha FullCalendar v7<br/>week / month / list]
C -->|events function: intervalo ativo| A[server action de leitura]
A --> L[activityPageData<br/>range limitado + overrideAccess false]
L --> D[DTO mínimo por evento]
C -->|slot| F[/atividades/nova<br/>horário + município prefilled]
C -->|evento| E[/atividades/slug<br/>detalhe existente]
C -->|drop / resize| W[rescheduleActivity]
W --> T[transaction + lock activity:id<br/>fresh actor + overrideAccess false]
T --> H[hooks Activity<br/>schedule + deputado]
W -->|falha| X[FullCalendar revert + feedback]
Decisões de engenharia
1. FullCalendar v7 como uma dependência route-local
Opções: A) @fullcalendar/react@7.0.2 com subpaths v7 | B) React v7 com plugins separados v6 | C) calendário próprio.
Recomendação: A — instalar @fullcalendar/react@7.0.2 e o peer temporal-polyfill, importando daygrid, timegrid, list, interaction, locale e tema pelos subpaths do próprio pacote. É MIT, declara React 19 e evita misturar majors. A ilha só entra no chunk de /campanha/agenda; next/dynamic com ssr: false entra apenas se o build provar que o pacote exige browser no import.
Rejeitadas: B — os pacotes separados publicados estão em v6.1.21 e criam incompatibilidade concreta; C — reimplementa seleção, week/month/list, drag, resize, teclado e touch fora do appetite.
2. activity permanece o único modelo; sem migration
Opções: A) calendar sobre activity | B) collection agenda | C) materialização paralela de eventos.
Recomendação: A — C14 já entregou startAt, endAt, tags, deputyPresent, município, status, índices e access.
Rejeitadas: B/C — duplicam ownership, exigem sincronização e não acrescentam produto.
3. Feed dinâmico por server action POST e intervalo visível
Opções: A) server action chamada pelo events function | B) GET JSON feed | C) carregar todo o histórico no RSC/browser.
Recomendação: A — o FullCalendar pede [start, end) ao navegar; a action autentica novamente e chama um loader no owner activityPageData. POST evita que o service worker de /campanha grave um GET autenticado em Cache Storage. O range é validado, exclusivo e limitado a 45 dias.
Rejeitadas: B — o service worker atual faz cache.put de GETs sob /campanha; exigiria outra exceção de segurança; C — payload sem limite e exposição desnecessária.
O where preserva eventos que atravessam a borda da vista:
startAt < rangeEnd
AND (endAt > rangeStart OR (endAt ausente AND startAt >= rangeStart))
Município, deputado presente e tag combinam entre si com AND. Atividades sem data continuam fora do calendário e disponíveis na lista antiga.
4. Contrato de filtro compartilhável, porém uma tag exata na v1
Opções: A) ?municipality=12&deputyPresent=1&tag=Comício | B) estado local | C) multi-tag já nesta fatia.
Recomendação: A — estender o owner client-safe activityUi.ts com parse, canonicalização, href e where da agenda. Ausência de deputyPresent significa todos; 1 significa somente com deputado. A tag é uma seleção exata entre valores acessíveis, preservando o contrato já entregue por C14 e deixando um link estável para C16.
Rejeitadas: B — não é compartilhável nem consumível por C16; C — exige fechar semântica OR/AND e UI de multisseleção sem necessidade para o aceite. Gatilho: C16 ou evidência da mesa de que um link precisa unir várias tags.
5. Remarcação estreita, não o update completo
Opções: A) action rescheduleActivity que aceita só id/startAt/endAt | B) chamar updateActivity | C) confiar apenas em editable no browser.
Recomendação: A — schema próprio, transação, fresh actor, advisory lock activity:<id>, leitura da linha com overrideAccess: false e update somente do horário. A política de deputado fica nomeada em access/activities.ts, é reutilizada pelo DTO/action/hook e o hook passa a considerar o estado original ou resultante de deputyPresent.
Rejeitadas: B — abre campos, demandas e parsing alheios ao gesto; C — affordance não é autorização.
A action retorna união serializável { ok: true } | { ok: false, message }. Falha chama revert() no eventDrop/eventResize; a recusa de deputado usa uma constante segura única, e demais falhas viram mensagem genérica.
6. Rotas antigas ficam vivas; agenda vira a entrada primária
Opções: A) nav e links primários para /agenda, mantendo /atividades | B) redirect global /atividades → /agenda | C) mover detalhe/form para /agenda.
Recomendação: A — nav “Agenda”, page chrome, quick actions, dossier e navegação assistida apontam à agenda; detalhe, criação, edição, giros e a lista de cards continuam nos URLs atuais. isCampaignNavActive reconhece /agenda e a subárvore /atividades como uma vertical.
Rejeitadas: B — descarta q/tab/status/page e deixa rascunhos de giro sem data sem superfície; C — quebra links, notificações e bookmarks sem ganho.
7. Detalhe existente em vez de drawer paralelo
Opções: A) evento navega para /campanha/atividades/[slug] | B) novo painel/drawer | C) modal com cópia parcial.
Recomendação: A — o detalhe já concentra tarefas, atualizações, resultado e edição, além de permanecer acessível por teclado via URL do evento.
Rejeitadas: B/C — duplicam dados e estados sem serem exigidos pelo aceite.
8. Bahia é o fuso explícito e a página continua dona do scroll
Opções: A) timeZone: 'America/Bahia', instantes UTC no servidor e height: 'auto' | B) fuso local do dispositivo | C) calendário com altura fixa e segundo scroll vertical.
Recomendação: A — callbacks usam strings ISO com offset/UTC e o formulário continua convertendo via campaignTime. height: 'auto' evita scroll vertical aninhado no shell. A toolbar compacta mantém Semana/Mês/Lista visíveis; touch usa o long-press nativo, mas formulário e botões continuam sendo as alternativas de teclado/touch.
Rejeitadas: B — desloca compromisso de quem estiver fora da Bahia; C — disputa scroll com CampaignContentScroll.
Componentes / mudanças
- Dependências (
package.json,pnpm-lock.yaml):@fullcalendar/react@7.0.2+temporal-polyfill; não instalar plugins v6 separados nem pacote premium. activityAgendaRequestSchema/activityRescheduleSchema(src/lib/schemas/activity.ts): range ISO limitado, filtros canônicos e payload mínimo de remarcação; constante segura da recusa de deputado.- Agenda URL/query (
src/utilities/activityUi.ts):ActivityAgendaState, parse/build/resolve de/campanha/agendaebuildActivityAgendaWhere; a lista antiga mantém o contrato atual. - Access (
src/utilities/access/activities.ts,src/utilities/campaignAccess.ts): política nomeada de remarcação; coordinator/candidate liberados, advisor só em compromisso sem deputado, leader negado. - DTO (
src/utilities/activityViewModels.ts): select mínimo eActivityAgendaEventcom id, title, URL/slug, start/end, status, tags, deputado, município/localidade ecanReschedule; sem Contact, liderança, tarefas ou documento Payload inteiro. - Loaders (
src/utilities/activityPageData.ts): eventos do range comuser + overrideAccess: false; tags conhecidas deduplicadas e ordenadas sobre atividades acessíveis; nenhuma cache longa para dado vivo de 2026. - Actions (
src/app/(campaign)/campanha/actions/activity.ts):loadActivityAgendaEventserescheduleActivity; remarcação sobwithPayloadTransaction+acquireTextAdvisoryLocks. - Defense in depth (
src/collections/Activity.ts): reutilizar a política nomeada no gate C14 e avaliar deputado no doc original ou resultante; sem alteração de schema/migration. - Rota (
src/app/(campaign)/campanha/(app)/agenda/page.tsx,loading.tsx): gatestaff, canonicalização da URL, opções de município/tags acessíveis, CTAs existentes e skeleton local. - Filtros (
src/components/campaign/activity/ActivityAgendaFilters.tsx): controles acessíveis de município, deputado e tag; URL viauseCampaignListFilterNavigation; loading/pending no resultado, não só no controle. - Calendário (
src/components/campaign/activity/ActivityAgenda.tsx+ CSS escopado): ilha FullCalendar comtimeGridWeek,dayGridMonth,listMonth,interaction, pt-BR e tema adaptado aos tokensdata-theme='campaign';eventsassíncrono, empty/error/loading, event click, slot click, drop/resize erevert(). - Criação prefilled (
atividades/nova/page.tsx,ActivityForm.tsx): aceitarstartAt/endAt/municipalityvalidados; município só é pré-selecionado se estiver nas opções acessíveis; reutilizar a action/form atual. - Chrome e caminhos (
campaignPaths.ts,campaignQuickActionPaths.ts,campaignPageChrome.ts,components/campaign/shell/nav.ts): separar “home da agenda” do root de detalhe de atividades, manter quick actions e estado ativo coerentes. - Links primários (
MunicipalityDossier.tsx,campaignNavigationUrls.ts, cancelamento do form quando for criação): apontar à agenda preservando filtros equivalentes; giro continua retornando à lista antiga para expor atividades sem data. - Migration: nenhuma. A migration C14 é história congelada e não será editada.
- Access / Consent: staff-only; leader fail-closed pelas barreiras de página/action/collection. Sem PII nova e sem Consent.
- UI: Impeccable D, mas dentro da linguagem atual: FullCalendar route-local, tokens da campanha, alvos de 44 px, estado não comunicado só por cor, evento com texto/ícone de deputado/status e CTA visível como alternativa ao clique/drag.
Dados → forma
- Forma escolhida: time grid semanal como decisão operacional primária; month para visão de distribuição; list para varredura linear e mobile/acessibilidade.
- Por quê: o job é conflito/encaixe no tempo, não comparação analítica; cards continuam úteis apenas como fila legada de sem-data e busca avançada.
- Rejeitadas: tabela (perde simultaneidade), cards como default (estado atual que C15 substitui), resources por assessor (premium e anti-goal).
Fontes oficiais verificadas
- React 17–19, instalação v7, plugins por subpath e integração Next: https://fullcalendar.io/docs/react
- Event source assíncrono e fim exclusivo do range: https://fullcalendar.io/docs/events-function
- Named time zone e Temporal: https://fullcalendar.io/docs/timeZone
eventDrop.revert(): https://fullcalendar.io/docs/eventDropeventResize.revert(): https://fullcalendar.io/docs/eventResize- Editabilidade por evento e
url: https://fullcalendar.io/docs/event-object - Touch por long-press: https://fullcalendar.io/docs/touch
height: 'auto'sem scrollbar interna: https://fullcalendar.io/docs/height
Fases verificáveis
- Tracer / contrato + server (~35%)
- Testes unitários primeiro para URL, range exclusivo/cap, combinação dos três filtros e política de remarcação.
- Schemas, policy helper, loader range/tags, DTO, action de leitura e action de remarcação.
- Testes de integração: coordinator/candidate movem compromisso com deputado; advisor move atividade comum do escopo, não move a do deputado; advisor fora do escopo e leader não leem/não movem; range e filtros não vazam linhas.
- UI funcional (~40%)
- Dependências v7, rota, filtros e ilha route-local com semana/mês/lista.
- Slot → form prefilled; evento → detalhe; drop/resize → action + revert; loading/error/empty.
- Nav/chrome/quick actions/links primários, mantendo lista/detalhe/giros antigos.
- Craft, critique e polish (~15%)
- Adaptar tema aos tokens, hierarquia de conteúdo e densidade da agenda.
- Browser/E2E em desktop e 390×844: toolbar, week/month/list, teclado, clique de evento, prefill e drag permitido; negação server-side fica pinada no int test.
- Confirmar que não há console error, scroll vertical aninhado nem indicador apenas por cor.
- Gates (~10%)
pnpm gate:fastdurante a iteração.pnpm format:check,pnpm exec knip,pnpm check:cycles, testes int/e2e afetados e build local no fechamento.- Push somente via
pnpm push; PR Ready + auto-merge apenas com required checks verdes.
Rabbit holes / Não escopo (engenharia)
- Sync Google, ICS/link de import e autenticação de feed: C16.
- Recorrência, resources, scheduler premium, calendários por assessor.
- Multi-tag OR/AND, filtros salvos, persistência de view/data no URL ou preferência de dispositivo.
- Drawer/modal de detalhe, quick-create paralelo e mudança das URLs de entidade.
- Tornar
startAtNOT NULL: giros E13 mantêm drafts intencionalmente sem data. - Corrigir em C15 defeitos adjacentes de C14 que não bloqueiam a agenda (escopo de município no create manual, status hidden no edit e política de notificações); revisar no
/simplifye capturar débito se pontuar. - Otimização raw SQL/distinct de tags antes de medida real; o loader acessível simples é a v1.
Riscos e mitigação
- Major incompatível: v7 concentra plugins em
@fullcalendar/react, enquanto pacotes separados estão em v6. Mitigação: pin único v7 + peer oficial; testes de build antes de craft. - Bundle: week/month/list/interaction + Temporal são pesados. Mitigação: imports apenas na ilha da rota, DTO mínimo e inspeção do chunk no build; sem
locales-allnem plugins premium. - Fuso: native
Datepode refletir o dispositivo mesmo com named zone. Mitigação: persistir UTC, usarstartStr/endStrcom offset e helpers Bahia; testes com instantes conhecidos. - RBAC: editabilidade client pode ficar stale. Mitigação: fresh actor, Payload access com
overrideAccess: false, policy no action/hook erevert()na UI. - Concorrência: dois drags podem sobrescrever horário. Mitigação: advisory lock por atividade e desabilitar nova mutação do mesmo evento enquanto a primeira está pendente.
- Range/performance: overlap correto consulta
endAtsem índice. Mitigação: range máximo de 45 dias, select mínimo e dado esperado pequeno; medir antes de migration de índice. - Mobile: semana de sete colunas é densa e touch drag exige long-press. Mitigação: toolbar que quebra sem overflow, conteúdo compacto, lista sempre a um toque, CTA/form como alternativa e E2E 390×844; não usar
dayMinWidth, que requer premium. - Atividades sem data: não renderizam em calendário. Mitigação: manter lista antiga e retorno do compositor de giros.
- Notificações: o hook atual notifica assessores em toda mudança, inclusive drag. Mitigação nesta fatia: preservar comportamento existente; se o browser test mostrar ruído de produto, capturar como decisão separada em vez de silenciar implicitamente.
Divergências da hipótese de direção
- Sem novo
activityAgendaData.ts: leitura e DTO entram nos ownersactivityPageData.tseactivityViewModels.ts, evitando twin e novo top-level pinado. - Sem GET feed: server action POST evita o cache explícito do PWA para GET autenticado.
- Sem painel de evento: o detalhe atual é a superfície operacional completa e vira o destino do clique.
- Sem redirect de
/campanha/atividades: a lista permanece como compatibilidade e fila de giros sem data; somente a entrada primária muda para/campanha/agenda. - Uma tag por link na v1: mantém o contrato C14 e cabe no appetite; multi-tag ganha gatilho explícito em vez de semântica inventada.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: week/month/list, três filtros combinados, slot/create, detalhe, drag/resize permitido e rotas antigas.
leadernegado e advisor limitado pelo access atual; nenhum loader/action usa Local API em nome do ator semoverrideAccess: false.- Remarcação é transacional, serializada por atividade e não usa o update amplo.
- FullCalendar e CSS não entram no bundle comum de
/campanha. - Fuso Bahia, range exclusivo, erro/revert, loading/empty e alternativas de teclado/touch testados.
- Sem schema change/migration; C14 permanece congelada.
Decision-quality: 5/5 — decisões caras têm alternativas, cabe no appetite, rabbit holes estão nomeados, owners existentes são reutilizados e o outcome não foi reescrito.