- Replace kind enum with free-form tags (text[] hasMany) - Remove origin and deadline fields - Status: remove rascunho/planejado, keep confirmado/realizado/cancelado - startAt required for user-facing creates (optional for tour drafts) - Add deputyPresent time gate (only coordinator/candidate can reschedule) - UI: calendar-like form with tag input, no origin/deadline, no draft status - E13 giros: tourStopRoleActivityKind → tourStopRoleActivityTags - Migration: kind→tags with label mapping, status remap, enum recreation - Activity texts table creation (was missing from migration history) Closes #389
13 KiB
Impl: Remodelar atividades para a agenda (calendário)
Status: aprovado Atualizado em: 2026-08-06 Issue: #389 Intenção: docs/plans/remodelar-atividades-para-agenda.md Appetite restante: ~1,5–2 dias eng (herdado)
Leitura da intenção
- Outcome: Remodelar o modelo/formulário de atividade para parecer compromisso de agenda — tempo + lugar + quem + tags livres — em ~1 minuto. Lista/detalhe/actions continuam usáveis; C15 traz o calendário por cima.
- O que NÃO negociar: remover
originedeadline; renomearkind→tags(livres); status enxutoconfirmado | realizado | cancelado; defaultconfirmado+startAtobrigatório; remarcar horário comdeputyPresentsó coordinator/candidate; leader lockdown intacto; nenhuma nova collection de pessoa (Contact). - O que reavaliar: hipótese da intenção de "omnibox de associados" — o formulário atual já tem
RelationMultiSelectpara orgs e checkboxes de assessores; uma omnibox mista (assessor + liderança + organização) é caro e o produto não mostrou dor real — rejeitada nesta leva (ver Rabbit holes).
Abordagem recomendada
flowchart TD
A[Migration: drop origin/deadline, kind→tags, status remap] --> B[schema activity.ts: tags string array, 3 statuses, startAt required]
B --> C[Activity.ts collection: tags field, remove origin/deadline/kind, status default confirmado]
C --> D[View models: tags/origin/deadline out, startAt always required]
D --> E[Form: tags input + autocomplete, no origin/deadline, status toggle só confirmado]
E --> F[Card/Omnibox/Dossier: tags badges, tag filter]
F --> G[E13 giros: tourStopRoleActivityTags, tags in stop draft]
G --> H[AI tools + notification hooks: adapt]
H --> I[deputyPresent write gate via beforeValidate]
I --> J[Gates: gate:fast + push]
Opções consideradas: A | B | C
Recomendação: B — text com hasMany: true (Payload 3.x nativo, armazena text[], indexável, queryable com contains) — porque é o mais simples que atende "tags livres + filtro" sem nova collection.
Rejeitadas:
- A —
arraycom campotextaninhado: mais verboso, cada tag é uma row com id, desnecessário para tags simples. - C —
relationshippara nova collectionActivityTag: super-engineering, a intenção diz "a mesa inventa" — não precisa catálogo administrado.
Decisões de engenharia
1. Tags: text com hasMany: true
Opções: A) text hasMany | B) array com text field | C) relationship a nova collection
Recomendação: A — Payload 3.x suporta nativamente, armazena como text[], filtro contains funciona sem join.
Rejeitadas: B — verbosidade desnecessária; C — nova collection sem necessidade, vai contra "tags livres".
2. Migração de kind → tags
Opções: A) migrar valores usando label map (comício → Comício) | B) migrar valores raw (comício) | C) descartar histórico
Recomendação: A — preserva legibilidade; as labels já são pt-BR amigáveis e é o que a UI sempre mostrou.
Rejeitadas: B — valores raw com underscore são feios como tag; C — perde histórico útil.
3. Remap de status antigos
Opções: A) planejado → confirmado, rascunho → cancelado | B) tudo → confirmado | C) tudo → cancelado
Recomendação: A — planejados tinham data, viram confirmados; rascunhos eram esboços sem data, cancelados é o destino honesto.
Rejeitadas: B — rascunhos sem data virariam "confirmados" sem data, quebrando a invariante; C — perde trabalho já planejado.
4. deputyPresent write gate
Opções: A) beforeValidate hook com role check | B) field-level access control | C) server action check
Recomendação: A — beforeValidate tem acesso a req.user, originalDoc, e data; cobre todos os caminhos (admin + server action).
Rejeitadas: B — field access não lê o doc atual facilmente; C — não cobre Payload admin.
5. Omnibox tag filter
Opções: A) filter por tag exata (contains) com autocomplete dos valores existentes | B) multi-tag filter | C) manter kind enum no filtro
Recomendação: A — atende o job "filtrar por tipo de compromisso" sem inflar; multi-tag é rabbit hole para C15.
Rejeitadas: B — scope creep; C — viola aceite de produto.
6. Formulário de tags (client)
Opções: A) tag input custom com datalist de valores conhecidos | B) Combobox multi-select | C) text field livre
Recomendação: A — datalist HTML nativo dá autocomplete sem JS extra; o servidor passa a lista de tags conhecidas via props. Combobox multi é overkill para v1; text livre não dá autocomplete.
Rejeitadas: B — dependência pesada para v1; C — sem autocomplete, viola opção B da intenção.
Componentes / mudanças
- Migration (
20260806_XXXXXX_c14_remodel_activity_agenda):- Add
tagscolumn (text[]) - Data:
tags = ARRAY[activity_kind_labels[kind]]where kind is not null - Remap:
planejado→confirmado,rascunho→cancelado - Drop
kind,origin,deadlinecolumns - Add NOT NULL default
confirmadoon status - JSON side: espelhar no
.json
- Add
src/lib/schemas/activity.ts: removeractivityKinds/activityOrigins/activityKindLabels/activityOriginLabels/ActivityKind/ActivityOrigin;activityStatuses→['confirmado', 'realizado', 'cancelado']; adicionarMAX_ACTIVITY_TAGS,MAX_ACTIVITY_TAG_LENGTH; schematags: z.array(z.string().trim().min(1).max(80)).max(20).optional(); removerkind/origin/deadlinedoactivityFieldsSchema;activityCreateSchemadefault status →confirmado;tourStopDraftSchema—kind→tags.src/collections/Activity.ts:tagsfield (text,hasMany: true,index: true,label: 'Tags'); removerkind/origin/deadlinefields;statusoptions → 3 valores, default'confirmado';startAtrequired;activityStaffFieldSnapshotatualizado;validateActivityScheduleadaptada (startAt sempre required); novovalidateDeputyPresentTimeGatehook;afterChangeremover check derascunho;defaultColumns— trocarkindportags.src/utilities/activityViewModels.ts: removerkind/origin/deadlinede todos os view models; adicionartags: string[];activityListSelect/activityFormSelect/activityDetailContextSelecttrocarkind/origin/deadlineportags.src/utilities/activityUi.ts:ActivityListState.kind→.tag;buildActivityListWhere—{ tags: { contains: state.tag } };isActivityKind→isActivityTag(string validation);parseActivityListParams—taginstead ofkind;activityTabsremoverrascunhos.src/utilities/activityOmnibox.ts:kindfilter →tagfilter; seeds fromactivityKindLabels→ from existing tags (server-provided); chipskind:→tag:.src/utilities/activityFormData.ts: removerkind/origin/deadlineparsing; adicionartagsparsing (fromtagsJsonbounded JSON field).src/components/campaign/activity/ActivityForm.tsx: removerkindselect,originselect,deadlinefield; adicionarActivityTagsField(tag input + datalist); status toggle: apenasconfirmadopara novo;startAtalways required.src/components/campaign/activity/ActivityCard.tsx:activityKindLabels[activity.kind]→ render tags as small badges.src/components/campaign/activity/ActivityStatusBadge.tsx: removerrascunho/planejadovariants.src/components/campaign/activity/ActivityFilters.tsx: kind → tag no omnibox.src/app/(campaign)/campanha/(app)/atividades/[slug]/ActivityOverviewTab.tsx: remover rows de deadline/origin; adicionar tags display.src/app/(campaign)/campanha/(app)/atividades/[slug]/page.tsx: kind badge → tags badges.src/components/campaign/municipality/MunicipalityDossier.tsx:activityKindLabels[activity.kind]→ tags badges.src/utilities/visit/visitPlannerViews.ts:tourStopRoleActivityKind→tourStopRoleActivityTags: Record<TourStopRole, string[]>(ancora: ['Comício'],satelite: ['Reunião de apoio'],semente: ['Reunião de apoio']).src/components/campaign/tour/TourComposerForm.tsx:kind→tags;ActivityKind→string[];origin→ removed;DEFAULT_STOP_ORIGIN→ removed.src/utilities/ai/tools/buildCampaignLinks.ts:kind: z.enum(activityKinds)→tag: z.string().optional();status: z.enum(activityStatuses)atualizado.src/utilities/ai/campaignNavigationUrls.ts:kind?: ActivityKind→tag?: string;activityKindsreference removida; filter logic adapted.src/utilities/notification/notificationEvents.ts:afterChangehookbecameVisiblecheck —rascunho→confirmado(since rascunho doesn't exist anymore,becameVisibleis always true for creates).src/utilities/access/activities.ts: adicionarcanUpdateDeputyPresentTimepara o gate do deputyPresent.tests/unit/activityUi.unit.spec.ts: atualizar para 3 statuses, tag filter.tests/unit/listOmniboxB128.unit.spec.ts: kind → tag.tests/unit/codebaseConventions.unit.spec.ts: vocabulary guard —actionPlan/plano de açãojá existe; adicionaractivityKindcomo forbidden? Não —kindviratags, não há vocabulário proibido novo.
Dados → forma
N/A — remodel de modelo, não apresentação de dados novos.
Fases verificáveis
-
Tracer / schema+server (~40% do appetite)
- Migration (drop/add columns + data migration)
src/lib/schemas/activity.ts— schema remodelsrc/collections/Activity.ts— collection remodel + hookssrc/utilities/activityViewModels.ts— view modelssrc/utilities/activityUi.ts— list state/where/paramssrc/utilities/activityFormData.ts— form data parsingsrc/app/(campaign)/campanha/actions/activity.ts— actionssrc/utilities/visit/visitPlannerViews.ts— giro tagssrc/utilities/notification/notificationEvents.ts— hook- Unit tests:
activityUi,listOmniboxB128 pnpm exec tsc --noEmit+pnpm test
-
UI (~40% do appetite)
ActivityForm.tsx— tags input, no origin/deadline/kindActivityCard.tsx— tags badgesActivityStatusBadge.tsx— 3 variantsActivityOverviewTab.tsx— no deadline/originActivityFilters.tsx/activityOmnibox.ts— tag filterTourComposerForm.tsx— tags per stopMunicipalityDossier.tsx— tags display- AI tools — tag/status
pnpm lint+pnpm buildagainst local DB
-
Gates (~20% do appetite)
pnpm gate:fastpnpm push -u origin HEAD- PR + auto-merge +
gh pr checks --watch --required
Rabbit holes / Não escopo (engenharia)
- Omnibox mista de associados (assessor + liderança + organização num só campo): a intenção menciona, mas o formulário atual já funciona com campos separados e o aceite não depende disso. Fica para C15 se a dor aparecer.
- Multi-tag filter: o filtro de lista aceita UMA tag por vez. Multi-tag é scope creep para C15.
- Recorrência / sync Google: fora de escopo (C16).
- FullCalendar /
/campanha/agenda: C15. - Redesign do compositor de giros: "só não quebrar sem destino" — adaptar os tipos, não mudar o fluxo.
- Catalog admin de tags: a intenção rejeita explicitamente (opção C). Tags são livres.
activityKindvocabulary guard: não adicionar — o termo some naturalmente com a migration.
Riscos e mitigação
- Migration destrutiva em prod: a migration dropa colunas. Revisar SQL antes do deploy. Dados de
kindsão migrados paratags;origin/deadlinesão descartados sem backup (a intenção aceita explicitamente). - E13 giros quebrado:
tourStopDraftSchemamuda dekindatags. O giro passa a enviartags: ['Comício']no lugar dekind: 'comicio'. Testar o fluxo end-to-end. - Omnibox sem tags existentes: o autocomplete de tags precisa de uma lista de valores já usados. Na listagem, isso vem do Payload (query distinta de tags existentes) ou de um endpoint. Mitigação: v1 usa
datalistpopulado pelo servidor via props da página (tags distintas dopayload.findna listagem). C15 traz um endpoint dedicado se preciso. - deputyPresent gate hook: o
beforeValidateprecisa leroriginalDoc.deputyPresente o role doreq.user. Se o actor for advisor e tentar mudarstartAt/endAtde atividade comdeputyPresent: true→ throw. Testar com fixtures de role.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (tags livres, 3 statuses, origin/deadline removidos, deputyPresent gate)
- Invariantes AGENTS/engineering-standards (transaction pattern, Contact convention, leader lockdown, naming)
- Testes de domínio previstos:
activityUi.unit.spec.ts,listOmniboxB128.unit.spec.ts,codebaseConventions.unit.spec.ts