Replace all project-local .cursor/ path references with .agents/ across rules, skills, environment config, hooks, and ignore files. Keep Cursor editor paths (~/.cursor/, window.cursor, CURSOR_API_KEY) and vendored Impeccable editor-hook paths unchanged.
21 KiB
Registrar sinal a partir da célula "Último sinal" da lista de municípios
Status: entregue (2026-07-25)
Atualizado em: 2026-07-25
Item do roadmap: docs/roadmap.md (Trilha B, item B26)
Impeccable: B — encaixe na célula lastSignal de /campanha/municipios (tabela desktop + card mobile); sem rota nova de UI
Appetite: ~0,75 dia eng; 1 controle novo + 1 form action + fields compartilhados; sem migration, sem collection, sem endpoint JSON
Responsável: —
Revisão de entrega (2026-07-25)
Entregue: MunicipalitySignalFields + MunicipalityListSignalControl (Popover desktop / Drawer mobile) na coluna "Último sinal"; createMunicipalityListSignalFormAction em municipalityStaffFormActions.ts; wiring em MunicipalityList + municipios/page.tsx; e2e dedicado. Correções da auditoria aplicadas: (1) form action no padrão try/catch das irmãs do arquivo — não runCampaignFormAction (esse arquivo ainda é hand-rolled); (2) sem novo teste int (access já coberto em campaignMunicipalityUpdate.int.spec.ts); (3) Drawer controlado sem DrawerTrigger. Gate: tsc/lint/format/knip/cycles/unit+int verdes; e2e do fluxo B26 verde; build verde. Aikido: 0 findings nos arquivos novos/editados.
Design (Impeccable)
Âncoras: PRODUCT.md (princípio 2 Clarity under pressure, princípio 3 Edit where you see, princípio 4 Auto-save, no Save button — e a exceção nomeada nele para escrita atômica multi-campo, princípio 8 Feel the action) / DESIGN.md (register product — Field Desk) · tema data-theme='campaign' · regras .agents/rules/campanha-edit-where-you-see.mdc (item 4: submit explícito continua válido para fluxo multi-campo) e .agents/rules/campanha-action-feedback.mdc · precedentes vivos: MunicipalityListTrendControl.tsx (Popover na célula) e MunicipalityUpdateForm.tsx (campos do sinal tipado do C12).
Na implementação (implement-roadmap-item): craft compacto → critique → polish. Sem shape completo: a célula, o Popover de lista e o formulário de sinal já existem no produto; o que é novo é a combinação e a apresentação mobile (primeira vez que um controle de célula abre em bottom sheet).
Brief compacto:
- Persona / contexto: Alex (Coordenador Geral) e Casey (Assessor) varrendo a fila de alocação — a lista está ordenada por déficit (default do E9) ou por frescor, e a coluna "Último sinal" é justamente onde o município grita "ninguém encosta aqui há 34 dias". No celular, em campo, logo depois de uma ligação ou de uma conversa no ZAP.
- Job principal: transformar a leitura "está frio" em registro no mesmo gesto — anotar o sinal ali, sem abrir o município, sem trocar de tela, sem perder o lugar na varredura.
- Estratégia de cor: Restrained (inalterada) — a única cor da célula continua sendo o âmbar
text-estimate-pending-foregrounddo estado frio (E9). O gatilho não ganha cor própria. - Edit where you see: sim — hoje a célula é o único readout puramente morto da faixa staff da linha (assessores, tendência e votos estimados já são editáveis desde B9/B19). O dado por trás dela, porém, não é um campo do município: é uma criação de
municipalityUpdate, o que muda o contrato (ver Decisões travadas). - Anti-goals: virar o formulário longo de atualizações dentro de um Popover (as 3 textareas do relatório semanal); spreadsheet/data-grid mode; segundo sistema genérico de célula editável; Popover ancorado espremido sob o teclado do celular; criar registro vazio "rascunho" só para ter o que auto-salvar.
Dados → decisão → apresentação
- Vou apresentar dados? Não.
Dados: N/A— o item é affordance de escrita. A leitura da célula (frescor E9:max(lastUpdateAt, lastPledgeAt), rótulo "há N dias", limiar frio de 21 dias) continua idêntica, e nenhuma métrica, série, ranking ou mapa novo entra. - Efeito de leitura a vigiar: depois de gravar, o próprio número muda (o município passa a "hoje"). Isso é o ponto — e é o motivo de a gravação revalidar em vez de fingir otimismo (ver Decisões travadas): o rótulo é resultado derivado, não valor de controle.
Contexto
Em /campanha/municipios, a coluna staff "Último sinal" nasceu no E9 (fila-de-alocacao.md): SignalAgeReadout renderiza municipality.lastSignalAt como "hoje" / "há N dias" / "Sem sinal", em âmbar com ícone quando passa de MUNICIPALITY_COLD_SIGNAL_DAYS (21). A coluna também é a chave de ordenação frescor. É um readout: para registrar qualquer coisa, o usuário precisa abrir /campanha/municipios/[slug]?tab=updates (ou ?newUpdate=1) e usar o MunicipalityUpdateForm, depois voltar e reencontrar o lugar na lista.
Os sinais tipados vieram do C12 (registro-fundacao.md): municipalityUpdate com kind: 'sinal' exige body, signalType (invasão / esfriamento / visita adversária / proposta a broker / outro) e signalSource, mais o checkbox staff-only triangulated. O registro é imutável para o staff (canMutateMunicipalityUpdate = só admin Payload), e o afterChange recomputa municipality.lastUpdateAt, que alimenta o frescor.
Pedido de produto em 2026-07-25 (mesma leva de B22/B23/B24): clicar na célula de sinal deve abrir um popover para criar um sinal novo; no celular, um bottom sheet ("dialog daqueles que vem de baixo"). O item fecha o laço da fila de alocação: hoje o E9 diz onde está frio e o produto obriga a sair da fila para fazer algo a respeito.
Objetivos
- Clicar na célula "Último sinal" (tabela desktop) abre um Popover com o formulário curto de sinal; no card mobile, um bottom sheet (
Drawer) com os mesmos campos. - O formulário grava um
municipalityUpdatecomkind: 'sinal'reusandocreateMunicipalityUpdate— mesma validação (zod + hook da collection) e o mesmo access do formulário longo. - Depois de gravar: célula atualizada pelo servidor (o município vira "hoje"), popover/sheet fechado, confirmação visível, e pendente honesto durante a revalidação (princípio 8).
- Erro (inclusive assessor fora da carteira) aparece dentro do popover/sheet, com o rascunho preservado — nada de fechar engolindo o texto.
- Toque confortável: gatilho e campos com
min-h-11; o sheet mobile respeita o teclado virtual. - Access inalterado (
canCreateMunicipalityUpdate: unrestricted vê tudo, assessor só a carteira,leadernão tem a coluna nem a lista). Sem migration, sem collection, semConsentnovo, sem endpoint JSON novo. - Ordenação/
ariado headerfrescor(B15) e o tooltip de coluna intactos.
Decisões travadas
- O submit continua explícito ("Registrar sinal") — este popover é a exceção do princípio 4, não uma regressão do B24. É uma criação multi-campo atômica:
body+signalType+signalSourcesão obrigatórios pelomunicipalityUpdateCreateSchemae pelovalidateMunicipalityUpdateKind, e o registro é imutável para o staff depois de criado. Rejeitado: auto-save por campo (cada debounce tentaria criar um registro inválido e, se algum passasse, viraria linha permanente no feed — o staff não pode editar nem apagar); criar registro vazio ao abrir e ir preenchendo (lixo no feed do município, no dossiê E16 e no frescor, já que qualquer update carimbalastUpdateAt). OPRODUCT.mdprincípio 4 e a regracampanha-edit-where-you-see.mdcitem 4 preveem exatamente isso ("write must be atomic across several fields"); o B24 (autosave-tendencia-lista-municipios.md) tira o "Salvar" de uma edição de campo único na mesma linha — os dois contratos convivem porque a natureza da escrita é diferente, e a diferença precisa estar visível na copy do botão ("Registrar sinal", não "Salvar"). - Só
kind: 'sinal'a partir da lista. A coluna se chama "Último sinal" e o C12 já dá ao sinal um vocabulário fechado (tipo + fonte + triangulado). Rejeitado: seletor dos 4kindno popover —semanalsozinho traz três textareas de 3000 caracteres mais dois números e transformaria o popover no formulário de detalhe (anti-goal do brief);nota/urgentecontinuam a um clique no?tab=updates, que segue sendo o lugar do registro completo. - Gravação por server action +
revalidateMunicipalityListPaths({ slug }), não por endpoint JSON com otimismo local. O que a célula mostra é resultado derivado (max(lastUpdateAt, lastPledgeAt)), e inventar "hoje" no cliente é o anti-goal literal do princípio 3 ("optimistic writes of list/aggregate results that skip server refresh"); além disso o novo sinal precisa aparecer no feed do detalhe e no dossiê E16 sem depender de sorte de cache. O custo é aceitável porque a escrita é um submit deliberado, não um debounce de digitação — diferente do B24 e do controle de votos estimados, que gravam várias vezes por minuto. Rejeitado:POST /campanha/municipios/signalespelhandoexpected-votes/route.ts(mais código, dado derivado mentiroso e detalhe/dossiê defasados);router.refresh()no cliente (mesmo custo de RSC, sem a revalidação do detalhe). - Popover no desktop,
Drawer(bottom sheet) no mobile, escolhidos pela divisão de breakpoint que a lista já tem — não poruseIsMobile().MunicipalityListjá renderiza dois ramos: cardsmd:hiddene tabelahidden md:block; cada ramo monta a sua variante e ambos compartilham um único componente de campos. Rejeitado:useIsMobile()(o hook existe emsrc/hooks/use-mobile.ts, mas hoje só oSidebarusa; num controle por linha ele adiciona hidratação em duas fases e um segundo critério de breakpoint concorrendo com o CSS que já decide o layout);Sheet side="bottom"(é Radix Dialog sem swipe; oDrawerdo@base-ui/reactjá é o idioma de "vem de baixo" do produto, usado noInstallPwaToast); manter Popover ancorado no mobile (o pedido de produto nasceu disso — popover ancorado num card estreito fica espremido e o teclado virtual cobre os campos). - O gatilho é a própria leitura de frescor, não um ícone extra. A célula vira um
buttoncujo rótulo acessível é "Registrar sinal em {município} — {rótulo de frescor}", preservando cor/ícone do estado frio. Rejeitado: botão "+" separado ao lado do texto (dois alvos numa célula densa, e o alvo útil vira o menor dos dois); coluna nova de ação (densidade morta — o fill-in de remover a coluna "Tipo" está indo na direção contrária). - i18n e naming (AGENTS.md): identificadores em inglês —
MunicipalityListSignalControl,MunicipalitySignalFields,createMunicipalityListSignalFormAction; strings visíveis em pt-BR ("Registrar sinal", "Tipo do sinal", "Fonte", "Triangulado", "Sinal registrado.").
Questões em aberto
- Ordenado por
frescor, a linha salta ao gravar. Revalidar mesmo assim? Opções: A) sempre revalidar (a linha se move); B) nunca revalidar (célula mente); C) revalidar sempre, mas nomear o município na confirmação para reancorar quem estava varrendo. Recomendação: C — mover a linha é o comportamento honesto (o município deixou de estar frio, que é o objetivo da fila), e o custo real é perder o lugar visual; a confirmação "Sinal registrado em Vitória da Conquista." resolve isso por ~zero. Sob o defaultdeficitnada se move. - As cinco descrições dos tipos de sinal (que o formulário longo lista embaixo do select) cabem no popover? Opções: A) não, só o select; B) lista completa como no detalhe; C) descrição do tipo selecionado, em uma linha, abaixo do select. Recomendação: C — mantém o popover curto e ainda ensina o vocabulário do C12 a quem está aprendendo (mesmo problema do débito O3/glossário); B ocuparia mais altura que o resto do formulário inteiro.
triangulatedentra no popover? Opções: A) sim, checkbox; B) não, só no detalhe. Recomendação: A — é um checkbox, é campo staff-only com access próprio já resolvido, e "confirmado por mais de uma fonte" é justamente o que se sabe na hora de registrar.- Confirmação:
Alertdentro do popover antes de fechar, ou toast depois de fechar? Opções: A) toast (padrão doMunicipalityListTrendControl); B)Alertde sucesso e o usuário fecha. Recomendação: A, para não deixar um popover aberto sobre uma lista que está revalidando — com a mensagem nomeando o município (ver primeira questão).
Abordagem proposta
flowchart LR
cell["Célula Último sinal<br/>(SignalAgeReadout)"] --> trig["button (min-h-11)"]
trig -->|"md+ (tabela)"| pop["Popover"]
trig -->|"< md (card)"| drw["Drawer bottom sheet"]
pop --> fields["MunicipalitySignalFields<br/>(texto, tipo, fonte, triangulado)"]
drw --> fields
fields -->|"submit"| fa["createMunicipalityListSignalFormAction"]
fa --> act["createMunicipalityUpdate<br/>(zod + transação + overrideAccess: false)"]
act --> hook["afterChange → municipality.lastUpdateAt"]
fa --> rev["revalidateMunicipalityListPaths({ slug })"]
rev --> cell
fa -.erro.-> err["Alert no popover/sheet<br/>+ rascunho preservado"]
Componentes:
MunicipalitySignalFields(novo,src/components/campaign/municipality/MunicipalitySignalFields.tsx): só os campos do sinal (bodytextarea 2 linhas,signalTypeNativeSelect+ descrição do tipo escolhido,signalSourceInput,triangulatedcheckbox) mais osfieldErrorsdo estado da action. ReusamunicipalitySignalTypes/municipalitySignalTypeLabels/municipalitySignalTypeDescriptionsdesrc/lib/schemas/municipalityUpdate.tse os shellsField/FieldLabel/FieldError. Consumido pelas duas variantes (Popover e Drawer) — e é a peça que oMunicipalityUpdateFormdo detalhe pode passar a reusar depois (ver Adiado com gatilho).MunicipalityListSignalControl(novo,src/components/campaign/municipality/MunicipalityListSignalControl.tsx): client component com propvariant: 'popover' | 'sheet',useActionStatesobre a form action,Spinner+disabledno submit,Alertde erro, live regionsr-only,setOpen(false)+ toast só no sucesso. O gatilho recebe oSignalAgeReadoutcomo children — a leitura E9 não é reimplementada.MunicipalityList(src/components/campaign/municipality/MunicipalityList.tsx): a célulalastSignal(coluna staff) passa a envolverSignalAgeReadoutno controle comvariant="popover"; o card mobile usavariant="sheet". Nova propsignalFormActionno mesmo formato das existentes (MunicipalityStaffFormAction).createMunicipalityListSignalFormAction(src/app/(campaign)/campanha/(app)/municipios/municipalityStaffFormActions.ts): casca no padrão try/catch +mapCampaignFormActionErrordas irmãs do arquivo — nãorunCampaignFormAction(esse arquivo ainda é hand-rolled; a troca do detalhe/runCampaignFormActioncontinua fill-in de higiene). LêmunicipalityId,body,signalType,signalSource,triangulatede omunicipalitySlugdoFormData(helpersrequiredRelationshipFormValue/optionalFormText/checkboxFormValue/optionalMunicipalitySlugFromForm+parseMunicipalitySignalType), chamacreateMunicipalityUpdate({ kind: 'sinal', … })erevalidateMunicipalityListPaths({ slug }).municipios/page.tsx: passa a nova form action paraMunicipalityList, ao lado detrendFormAction/advisorsFormAction.- Migration: nenhuma.
municipalityUpdatee todos os campos do sinal existem desde o C12;lastUpdateAtjá é derivado por hook. - Testes: int cobrindo o access da nova form action (assessor fora da carteira recebe erro e nada é criado; assessor da carteira cria e
lastUpdateAtmuda) emtests/int/campaignMunicipalityUpdate.int.spec.ts; e2e emtests/e2e/campaignMunicipalities.e2e.spec.ts— abrir a célula na tabela, preencher, submeter, ver a célula virar "hoje".
Dependências
- Nenhuma dura em aberto. Precisa de E9 ✓ (a coluna e
lastSignalAt) e C12 ✓ (sinal tipado + imutabilidade), ambos entregues. - Reusa:
createMunicipalityUpdate(src/app/(campaign)/campanha/actions/municipalityUpdate.ts),municipalityUpdateCreateSchema(src/lib/schemas/municipalityUpdate.ts),canCreateMunicipalityUpdate(src/utilities/access/municipalityUpdates.ts),revalidateMunicipalityListPaths(src/utilities/municipalityRevalidation.ts),runCampaignFormAction,Drawer/Popoverdesrc/components/ui. - Suave: B24 (o popover vizinho na mesma linha; a diferença de contrato precisa ser deliberada, não acidental — quem chegar depois cita o outro na copy do botão), B23 (se o
cellTooltipfor estendido à coluna "Último sinal", vale o mesmo cuidado registrado lá:openOnTouch={false}+disabled={open}para o tooltip não roubar o tap nem sobreviver atrás do Popover), E9 ✓ (a fila que este item torna acionável).
Não escopo
- Registrar
semanal/nota/urgentepela lista → continua no detalhe (?tab=updates, deep link?newUpdate=1). - Ler o texto do último sinal na célula → hover de conteúdo é B23 (tooltip-celulas-listas.md); o feed completo é o detalhe / o dossiê E16 ✓.
- Tirar o "Salvar" do popover de Assessores → fill-in próprio já registrado no B24.
- Editar/apagar um sinal registrado → fora por decisão do C12 (registro imutável; correção é novo sinal).
- Migrar
createMunicipalityUpdateFormAction(detalhe) pararunCampaignFormAction→ higiene, fill-in.
Rabbit holes
- "Já que abriu um formulário na célula, deixa registrar qualquer atualização." Entram o seletor de
kind, três textareas de 3000 caracteres e dois campos numéricos; o popover vira o formulário do detalhe e a lista vira tela de edição. Mitigação neste item: sókind: 'sinal', campos fixos, nada de seletor de tipo de registro. - "São dois controles com Popover/Drawer, extrai um
ResponsiveQuickEditgenérico." Com B9/B19/B24 na mesma linha, a tentação é umEditableCellque acomode select, número por cenário, textarea, criação e edição — design system paralelo (anti-goal do princípio 3). Mitigação: controle nomeado; shell responsivo compartilhado só no 3º call site (ver Adiado com gatilho). - "Mostra o último sinal dentro do popover para dar contexto." Exige carregar o último
municipalityUpdatede cada linha da página (query por linha ou novo agregado), justo na lista que o Pass 2 otimizou para uma passada. Mitigação: adiado com gatilho abaixo. - "Aproveita e faz a linha não se mexer depois de gravar." Leva a congelar ordenação no cliente, a keys estáveis artificiais e a uma lista que mente sobre o próprio critério de ordem. Mitigação: revalidar e reancorar por copy (questão em aberto, opção C).
- Bottom sheet e teclado virtual. Sheet com altura fixa + teclado aberto esconde o submit; a correção "rápida" costuma virar cálculo de
visualViewportà mão. Mitigação: usar oDrawercomo ele já está configurado (max-heightpordvh, conteúdo rolável) e testar no iOS antes de inventar layout.
Adiado com gatilho
- Shell responsivo compartilhado (Popover ↔ Drawer) para controles de célula. Revisitar quando: existir o 3º controle de lista que precise das duas variantes.
- Reuso de
MunicipalitySignalFieldsdentro doMunicipalityUpdateFormdo detalhe. Revisitar quando: este item estiver em produção e os dois blocos de campos tiverem divergido em algum detalhe visível (hoje seriam dois consumidores no mesmo dia — extrair é barato, unificar copy/erros no mesmo passe é que estoura o appetite). - Lazy-mount de
Popover/Draweraté o primeiro open (custo idle do ramo CSS-oculto). Revisitar quando: perfilar a lista com vários controles dual-branch montados e o idle cost aparecer no trace — aplicar em lote nos controles da linha, não só neste.
Referências
docs/roadmap.md(Trilha B, B26; grafo; Janela 1–2; cortes seguros)src/components/campaign/municipality/MunicipalityList.tsx— colunalastSignal,SignalAgeReadout, card mobile,signalHintsrc/components/campaign/municipality/MunicipalityListTrendControl.tsx— precedente de Popover na célula comuseActionStatesrc/components/campaign/municipality/MunicipalityUpdateForm.tsx— campos do sinal tipado a fatiarsrc/app/(campaign)/campanha/actions/municipalityUpdate.ts—createMunicipalityUpdate(transação +overrideAccess: false)src/collections/MunicipalityUpdate.ts—validateMunicipalityUpdateKind, imutabilidade, recomputo delastUpdateAtsrc/utilities/access/municipalityUpdates.ts—canCreateMunicipalityUpdatesrc/app/(campaign)/campanha/(app)/municipios/municipalityStaffFormActions.ts— onde a nova form action entrasrc/components/ui/Drawer.tsx/src/components/ui/Popover.tsx— primitivosdocs/plans/fila-de-alocacao.md(E9) edocs/plans/registro-fundacao.md(C12) — origem da coluna e do sinal tipadodocs/plans/autosave-tendencia-lista-municipios.md(B24) — contrato vizinho, deliberadamente diferente- AGENTS.md — Campaign auth, naming pt-BR/inglês,
overrideAccess: false, transações PRODUCT.md/DESIGN.md— princípios 2, 3, 4 e 8; Field Desk · regrascampanha-edit-where-you-see.mdc,campanha-action-feedback.mdc