teqo-backup/.cursor/rules/projects/nucleos-eleitorais.mdc
Francisco Ignácio Fontoura Solla b0f4ebc1ed Add E2 TSE 2014/2018 vote series and historical trend insights.
Extends the electoral baseline with multi-year seeding, computeVoteTrend, list/detail UI, and registers post-simplify follow-ups as E7.
2026-07-19 05:09:43 -03:00

114 lines
29 KiB
Text
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
description: Estado do projeto Núcleos Eleitorais
alwaysApply: false
---
# Núcleos Eleitorais
## Status
- **MVP Ciclo 1 entregue e enviado em `main` (2026-07-18):** ondas 1–8 (auth/RBAC, domínio+UI de Núcleo/Liderança/Inteligência/Atualizações/Convites, dashboard, hardening) + refactors de composição Next.js, primitivos compartilhados, locks PostgreSQL, fixtures E2E e migration consolidada `20260718_010733_consolidate_campaign_schema`.
- **Ciclo 2 entregue, mesclado e deployado (2026-07-18):** A1 território multi-município/bairro, A3 baseline TSE 2022 (modelo + import), B1 overview da lista, C1 compartilhar página e D1 PWA — detalhes no item datado abaixo.
- **A2 entregue e mesclado em `main` (2026-07-18):** cadastro estático município↔ZE (`bahiaTseZones`, TSE 2024) + chips opt-in no formulário (`NucleusTerritoryAndZonesFields` / `territorySuggestions`); sem migration. Plano: [`docs/plans/zonas-por-municipio.md`](../../../docs/plans/zonas-por-municipio.md).
- **A4 Baseline no produto + Gap vs 2022 implementado e mesclado em `main` (2026-07-18):** agregação `getNucleusElectoralBaseline` / `loadNucleusBaseline2022Overview` + `computeGapVs2022`; UI `NucleusElectoralBaseline` + `NucleusInsights` na aba Visão geral; card "Baseline 2022" no overview da lista; chapa via `BASELINE_TICKET_2022`. Sem migration. Simplify no PR; débitos de escala → **A7** ([`escala-dry-pos-a4.md`](../../../docs/plans/escala-dry-pos-a4.md)). Plano pai: [`baseline-eleitoral-tse.md`](../../../docs/plans/baseline-eleitoral-tse.md).
- **A7 Escala e DRY pós-A4 registrado (2026-07-19):** agregar ranking federal no detalhe, filtro por `cityCode` TSE, Alert `confirmed` + `Progress`. Plano: [`docs/plans/escala-dry-pos-a4.md`](../../../docs/plans/escala-dry-pos-a4.md).
- **C3 Planos de Ação implementado (2026-07-18):** collection `actionPlan` + vertical `/campanha/planos` (lista com tabs Próximos/Todos/Realizados/Rascunhos, detalhe com tabs Visão geral/Tarefas/Atualizações, forms novo/editar), blocos "Próximos eventos" no overview de núcleos e no dashboard; `startAt` opcional só em rascunho; access por `coordinators`/`leadership`; migration `20260718_222832_add_action_plan`.
- **B2 Mapa Fase 1 (geometrias) entregue (2026-07-18):** TopoJSON estático municípios IBGE (`bahia-municipalities.topo.json`, ~132 KB, object `municipalities`) + TIs por dissolução (`bahia-identity-territories.topo.json`, ~15 KB, object `territories`); tabela `bahiaMunicipalityCodes` + `codeForMunicipality` / `municipalityForCode`; helpers `bahiaGeometries` (`getMunicipalityFeature` / `getTerritoryFeature`); script re-executável `pnpm build:geometries` (cache `data/geometries/`, sem DB); testes int de bijeção/cobertura/teto de bytes. Sem migration, sem UI (Leaflet = B3). Plano as-built: [`docs/plans/mapa-bahia-geometrias.md`](../../../docs/plans/mapa-bahia-geometrias.md).
- **B5 registrado (2026-07-18):** débitos de escala/DRY pós-B2 do `/simplify` que não entraram no cleanup (lazy load mun/TI + helper `ensureCachedDownload` para `build:geometries` / `db:seed:tse`) — plano [`docs/plans/escala-dry-pos-b2.md`](../../../docs/plans/escala-dry-pos-b2.md); F1 preferencialmente com B3; F2 cortável.
- **C7 registrado (2026-07-18) / entregue (2026-07-19):** débitos de escala/DRY pós-C3 do `/simplify` — plano [`docs/plans/escala-dry-pos-c3.md`](../../../docs/plans/escala-dry-pos-c3.md); composição territorial, shell assíncrono de contato, leituras por aba, short-circuit de hooks. Débitos pós-`/simplify` → **C11** ([`docs/plans/escala-dry-pos-c7.md`](../../../docs/plans/escala-dry-pos-c7.md)).
- **Trilha E registrada (2026-07-19) — mapa de projeção por município:** plano E1–E5 para equiparar e superar as planilhas "Mapa de projeção de votos Solla 2026" (`docs/sheets/`): E1 metas em cenários (`voteGoals` Bom/Regular/Mínimo) + `priority` no núcleo (migration compartilhada com E3), E2 série histórica TSE 2014/2018 + `computeVoteTrend` derivado (sem migration), E3 `dobradinhaNotes`/`nextSteps` staff-only na inteligência, E4 import único `pnpm db:seed:mapa` (sem criar `Contact`/`leadership`), E5 Salvador por bairro registrado como futuro. Plano: [`docs/plans/mapa-projecao-municipios.md`](../../../docs/plans/mapa-projecao-municipios.md).
- **E2 entregue (2026-07-19):** seed TSE parametrizado (`pnpm db:seed:tse -- --year=2014|2018|2022`; anos históricos só dep. federal T1 BA), `computeVoteTrend` ±10% (`increase|stable|decline|noBaseline`), loader candidate-only multi-ano, série + badge no `NucleusElectoralBaseline`, Alert de tendência no `NucleusInsights`, card "Tendência histórica" no overview da lista. Sem migration.
- Fluxos operacionais cobertos: login isolado, CRUD/arquivo de núcleos por slug, designação de coordenador (`geral`), CRM de lideranças, estimativas sugerir/confirmar com versão UUID, feed de atualizações, convites WhatsApp (`wa.me` + hash de uso único), dashboard com agregados só de núcleos ativos.
- Pendência operacional (não de código): textos provisórios Onda 0 provisionados por migration ([`docs/plans/onda-0.md`](../../../docs/plans/onda-0.md)); substituição pela assessoria jurídica eleitoral + hold de PII real de lideranças/apoiadores até lá; smoke pós-deploy Vercel. Ver Onda 0 em [`docs/roadmap.md`](../../../docs/roadmap.md).
- Em 2026-07-17, a listagem de Núcleos passou a aplicar filtros automaticamente pelo estado da URL, sem botão de confirmação, com comboboxes territoriais estritos compartilhados com o formulário.
- Em 2026-07-17, o contato principal passou a usar busca remota limitada e escopada no detalhe do núcleo, sem serializar a lista completa de lideranças.
- Em 2026-07-17, o feed paginado de atualizações e a prévia das três mais recentes passaram a usar loaders separados por aba, sem consulta de prévia fora da visão geral.
- Em 2026-07-17, o painel de lideranças passou a restaurar foco deterministicamente no fechamento de Sheet/Drawer e ganhou E2E real de URL, histórico, responsividade e privacidade de Flight.
- Em 2026-07-17, o login de campanha removeu React Hook Form/Zod do bundle cliente em favor de formulário nativo com `useActionState`; `Table` voltou a ser módulo estático sem fronteira cliente.
- Em 2026-07-17, os filtros da lista passaram a montar uma única árvore de controles em um disclosure responsivo; o estado canônico vindo do servidor remonta a ilha por chave de query, sem sincronização por `useSearchParams`.
- Em 2026-07-17, a composição Phase 1 separou o cartão estático de coordenação no servidor dos controles cliente; opções elegíveis e revisão do Núcleo agora são carregadas somente ao abrir o seletor. Editores pesados de inteligência, estimativa, atualização, liderança e convite passaram a fronteiras lazy locais.
- Em 2026-07-17, os shells lazy passaram a manter seus gatilhos Radix montados durante carregamento e edição, com restauração real de foco validada no navegador; o carregamento de coordenação permanece cancelável e só bloqueia fechamento durante a gravação.
- Em 2026-07-17, falhas nos chunks lazy de inteligência, atualização, convite e estimativa ganharam estado de erro acessível, fechamento seguro e nova tentativa controlada sem rejeição não tratada ou spinner infinito.
- Em 2026-07-17, o fluxo lazy de estimativa passou a transportar uma intenção explícita de foco através do refresh RSC: sugestão foca revisão, confirmação e edição focam o gatilho de editar, com fallback estável no cartão.
- Em 2026-07-17, a Refactor Phase 2C centralizou os advisory locks transacionais PostgreSQL e separou namespaces por domínio, com regressões concorrentes validadas.
- Em 2026-07-17, o follow-up Phase 2C tornou `contact-phone:<normalizado>` um invariante único para todo create/update de `Contact`; mudanças bloqueiam telefones antigo+novo em ordem determinística, rejeitam outro titular sem merge e preservam o convite em rollback.
- Em 2026-07-17, a Refactor Phase 2D reduziu `actions/invite.ts` a uma orquestração de 44 linhas e separou repositório SQL, criação e resgate em módulos `server-only`, preservando 488 testes de integração.
- Em 2026-07-17, a Refactor Phase 4A consolidou as dez migrations locais não publicadas de `20260717_*` em `20260718_010733_consolidate_campaign_schema`, mantendo intacta a história rastreada até `20260716_010420_add_campaign_user`; os bancos locais foram reconciliados sem alterar dados de aplicação.
- Em 2026-07-18, o follow-up Phase 4C fixou o Playwright em dois workers por padrão, adicionou guardas automáticos de erros do navegador/console/5xx, fortaleceu privacidade HTML+Flight por papel e tornou o login por teclado uma interação real com Enter e cookie verificado.
- Em 2026-07-18, a projeção do dashboard omite `supportStatus` ausente por redação de acesso e lança invariante genérico se um valor não-vazio inválido chegar à fronteira; agregação e badge são exaustivos no enum.
- Em 2026-07-18, os designs UX Pilot dos próximos ciclos foram versionados em `docs/design-refs/latest/` (11 pares `.png`+`.html`) e mapeados aos itens do roadmap — tabela "Referências de design (UX Pilot)" em `docs/roadmap.md`, com seção "Referência visual (UX Pilot)" em cada plano. Decisão: a UX/estrutura dos designs é a referência; a paleta NÃO — os arquivos vieram na paleta antiga (vermelho escuro/navy/dourado) e toda implementação usa os tokens claros do tema `data-theme='campaign'`. Sem design nesta leva: dobradinha, mapa, demandas, detalhe do plano de ação, opt-in de push e fill-ins.
- **Em 2026-07-18, o Ciclo 2 foi mesclado e deployado: A1, A3, B1, C1 e D1.**
- **B1 Overview da lista** — painel agregado entre filtros e lista em `/campanha/nucleos` (`NucleusListOverview`, `loadNucleusListOverviewData`): estimativa de votos confirmada + % + sugestões pendentes (staff), cobertura de coordenador e prévia de 3 atualizações, tudo sobre o conjunto **filtrado** inteiro (`buildNucleusListWhere`, `pagination: false`), oculto quando vazio. `lideranca` vê o overview com select reduzido, sem contagem de sugestões e só as próprias atualizações.
- **C1 Compartilhar núcleo** — `ShareNucleusDialogShell` no header do detalhe; destinatários carregados sob demanda por Server Action de leitura (`loadNucleusShareRecipients`), não no DTO da página. Loader confirma acesso ao núcleo (`overrideAccess: false`) e então lê nome+telefone com `overrideAccess: true` (evita N+1 de field access); lideranças só `engajado`; seção de lideranças omitida para o papel `lideranca`; `canReadCampaignUserPhone` passou a liberar telefone de `geral` para qualquer usuário de campanha. Compartilhar envia só o link — não cria convite nem concede acesso.
- **D1 PWA** — manifest + SW servidos por route handlers sob `/campanha` (script em `campaignPwa.ts`), cache `campanha-<buildId>` com `skipWaiting`/`claim`, navegação network-first com fallback `/campanha/offline`, RSC/Flight e `/campanha/convite/*` jamais cacheados; ícones em `public/campaign-icons/`; `InstallPwaToast` (Android `beforeinstallprompt`, iOS Drawer, dispensa em `sessionStorage`); logout limpa Cache API no cliente antes da action.
- **A3 Baseline TSE 2022 Fase 1** — collections `electionTally`/`electionCandidateVote`/`electionCandidate` (grupo `Dados Eleitorais`, leitura para `campaignUser`/`users` via `canReadElectionData`, escrita admin-only), migration `20260718_195854_add_election_results`, seed local `pnpm db:seed:tse` (idempotente por escopo year/office/turn, delete+bulk insert via drizzle, guard de banco local). Sem PII (sem CPF/título); identidade cross-ano por `identityKey` hash. (UI do baseline = A4, item de status acima.)
- **Em 2026-07-18, C2 Cadastro nominal de apoiadores — engenharia pronta e mesclada em `main` (pendente deploy + lote jurídico).** Collection `supporter` (join `Contact`↔campanha, núcleo opcional), migration `20260718_222656_add_supporter` com `UNIQUE NULLS NOT DISTINCT (contact_id, nucleus_id)`, consent por chaves `apoiador-cadastro` / `apoiador-intencao-voto` via `campaignConsent.ts` genérico, actions (create / intenção / import CSV só `geral` / remover dados), UI `/campanha/apoiadores` (lista+KPIs, ficha, wizard import, kit mínimo `wa.me`). Telefone obrigatório; `lideranca` sem acesso à área. Produção com dados reais espera deploy (build Vercel aplica a migration) + Consent keys + aprovação jurídica (Onda 0).
- **Em 2026-07-18, C6 Escala e DRY pós-C2 registrado no roadmap** (após `/simplify` do C2): shells compartilhados com listas de núcleos, import bulk drizzle + skip phone-invariant, preview token, KPI agregado SQL, StrictCombobox/AlertDialog. Plano: [`docs/plans/escala-dry-pos-c2.md`](../../../docs/plans/escala-dry-pos-c2.md). Depende do merge de C2; fases 3–5 cortáveis se a base permanecer pequena.
- **Em 2026-07-19, C9 Escala e DRY pós-C8 entregue:** `supporterListFilters.ts` (filtro unificado Payload↔SQL + `contactSearchQuery`), `loadSupportersPageData` (1× lookup de núcleos do coordenador), `apoiadores/[id]/formActions` no mapper compartilhado, `fieldError` nos 8 componentes de form restantes. Plano: [`docs/plans/escala-dry-pos-c8.md`](../../../docs/plans/escala-dry-pos-c8.md).
- **Em 2026-07-19, C10 Escala e DRY pós-C9 registrado** (após `/simplify` do C9): dedup de access na lista (`req.context`), query única de núcleos do coordenador, `errorProps` nos forms grandes. Plano: [`docs/plans/escala-dry-pos-c9.md`](../../../docs/plans/escala-dry-pos-c9.md).
- **Em 2026-07-19, C11 Escala e DRY pós-C7 registrado** (após `/simplify` do C7): feed O(n) condicional, loaders do detalhe + `loadCampaignUserNamesById`, selects por aba, hot paths mutação/form, utilities de busca/label. Plano: [`docs/plans/escala-dry-pos-c7.md`](../../../docs/plans/escala-dry-pos-c7.md).
## Decisões
- Núcleo Eleitoral é a unidade operacional; Zona TSE é uma referência oficial adicional.
- Todo núcleo exige geografia; natureza organizativa e setor são dimensões complementares.
- Exclusão no app é substituída por arquivamento.
- `lastUpdateAt` é mantido pelo domínio de atualizações (`nucleusUpdate`) sob advisory lock; não é mais placeholder.
- `Contact` tem e-mail e cidade opcionais no banco, telefone normalizado/indexado e acesso por escopo; os schemas públicos continuam exigindo e-mail (e cidade onde aplicável).
- `Leadership` é a junção única contato↔núcleo; acesso de liderança e contato exige vínculo `engajado`, e avaliação interna não é serializada para a titular.
- A UI de liderança usa view models separados: coordenação recebe avaliação interna; papel `lideranca` recebe somente a própria ficha sem `supportStatus`, `notes` ou `consentNote`.
- A deduplicação de `Contact` por telefone usa `pg_advisory_xact_lock(hashtextextended(phone, 0))` na própria sessão Drizzle da transação Payload, evitando duplicatas entre instâncias concorrentes.
- O DTO da própria liderança contém somente nome, celular, e-mail, setor e confirmação pela pessoa.
- “Convidar pelo WhatsApp” cria convite de uso único e abre `wa.me` no navegador; os E2E substituem `window.open` e validam a URL sem navegar para o WhatsApp.
- Sugestões de estimativa não alteram o valor confirmado; confirmação exige coordenação geral ou coordenador designado, deriva autoria/data no servidor e exige justificativa quando ajusta a proposta.
- Sugestão e confirmação da estimativa usam o mesmo `pg_advisory_xact_lock` por núcleo na sessão exata da transação Payload, serializando concorrência entre instâncias.
- Em 2026-07-17, cada sugestão de estimativa passou a receber uma versão UUID derivada no servidor; confirmações vinculam e comparam essa versão sob o mesmo lock, impedindo confirmações ABA obsoletas mesmo quando o valor volta a ser igual.
- Em 2026-07-17, links de convite passaram a exigir `NEXT_PUBLIC_SITE_URL` HTTPS e não local em produção; desenvolvimento/teste preferem a origem HTTP real da requisição local, sem confiar em `Host`/`X-Forwarded-*` sobre a configuração de produção.
- Em 2026-07-17, a origem de convites foi endurecida: produção ignora headers e exige `NEXT_PUBLIC_SITE_URL` como origem HTTPS exata (sem credenciais, path, query ou fragmento); desenvolvimento/teste só aceita headers para `localhost`, `127.0.0.1` ou `::1` exatos e usa a configuração explícita como único fallback.
- O detalhe do núcleo usa selects/DTOs discriminados por papel: liderança recebe apenas identificação, território básico, Zonas TSE e estimativa confirmada; inteligência estratégica e metadados de proposta/auditoria ficam restritos ao staff.
- Componentes React novos da Onda 4B usam arquivo PascalCase idêntico ao export principal; a renomeação dos componentes legados fica para a varredura separada.
- O consentimento de autopreenchimento é resolvido exclusivamente pela chave `lideranca-autopreenchimento`; ausência bloqueia criação e resgate sem fallback por ID.
- Convites persistem somente SHA-256 do token aleatório de 32 bytes, expiram em sete dias e revogam o convite ativo anterior do mesmo tipo/vínculo.
- O consumo usa `UPDATE ... WHERE` transacional com estado ativo e expiração, garantindo uso único mesmo sob corrida; falhas posteriores fazem rollback e preservam o convite.
- Autopreenchimento altera somente contato público, setor e consentimento; login exige vínculo engajado e só recupera uma conta existente quando `leadership.user` já aponta exatamente para ela. Coincidência de username sem vínculo é rejeitada, e uma conta nova sempre nasce como `lideranca`.
- `campaignUser.phone` é o celular opcional de contato; `username` permanece exclusivamente identidade de autenticação e nunca alimenta DTOs de contato. Leitura do telefone exige admin, titular, geral ou vínculo contextual por núcleo acessível.
- A ficha de liderança recebe somente `{ configured: boolean }` sobre o Consent; login fica indisponível fora de `engajado`, enquanto Consent ausente desabilita todos os convites com estado explícito.
- A rota pública `/campanha/convite/[token]` consulta exclusivamente o hash e serializa nome/celular/e-mail/gênero/setor/texto de Consent; estados inexistente/usado/expirado são indistinguíveis, sem avaliação interna.
- A rota pública força renderização dinâmica e no-store, usa `noindex,nofollow,nocache` e `referrer: no-referrer`; o resgate de login define o cookie isolado existente e redireciona apenas para `/campanha`.
- O Consent aceito só é preservado sem novo checkbox quando seu ID coincide com o documento atualmente configurado pela chave estável; versão diferente exige aceite explícito antes da troca, e rejeições fazem rollback sem substituir a relação anterior.
- O token bruto não é persistido nem enviado em campos de perfil. A verificação E2E mostrou que o Next.js serializa o segmento dinâmico e o argumento ligado da Server Action no HTML/Flight da própria página; a fronteira de segurança comprovada é `no-store`, `noindex`, `no-referrer`, nenhum request de terceiro e links externos com `noreferrer`. O token continua inevitavelmente presente na URL/documento same-origin.
- Campos opcionais self-service distinguem ausente (`undefined`, mantém valor) de vazio explícito (`null`, limpa valor), e o texto Lexical do Consent usa o renderer JSX oficial do Payload para preservar estrutura sem HTML injetado.
- O login de campanha garante alvos de toque mínimos de 44 px para identificador, senha e submit, com foco visível e ordem de teclado testada.
- A validação do login permanece autoritativa no servidor por `campaignLoginSchema`; o cliente usa apenas constraints nativas, metadados de autofill e estado pendente/erro da Server Action.
- Em 2026-07-17, toda senha recebida por `FormData` passou por uma fronteira central que rejeita ausência, vazio e `File`, mas preserva exatamente espaços e demais caracteres; apenas identificadores continuam normalizados.
- O shell mantém o documento sem overflow horizontal e o conteúdo em scroll interno nas larguras 360, 390, 768 e 1440 px.
- Em 2026-07-17, os caminhos internos foram renomeados para inglês: route group `(campaign)` e componentes em `src/components/campaign`; o segmento real `campanha` foi preservado, portanto as URLs continuam `/campanha`.
- Em 2026-07-17, Bahia passou a ser implícita no Núcleo. O território usa `region`, `city`, `neighborhood`, `locality` e `territoryNotes`; `state`, `territoryKind`, coordenadas e raio foram removidos. Região/cidade devem seguir a composição oficial vigente dos Territórios de Identidade.
- Em 2026-07-17, a composição oficial dos 417 municípios foi incorporada a partir da lista municipal da SECULT Bahia, validada pelos 27 códigos/contagens do mapa SEI 2024 (versão DPA 20/12/2024) e pela cobertura exata de `CitiesByState.BA`. O arquivo documenta as URLs oficiais; o formulário sincroniza município/território e o servidor rejeita pares incompatíveis.
- Em 2026-07-17, Núcleos receberam `slug` canônico único e as rotas passaram a `/campanha/nucleos/[slug]`. Para manter links duráveis sem uma tabela de aliases desproporcional neste ciclo, o nome ficou imutável após a criação; IDs permanecem internos nas relações e ações.
- Em 2026-07-17, responsáveis por Núcleo passaram a aceitar `campaignUser.role = geral|coordenador`; `lideranca` é rejeitada também em escritas diretas da Local API. Nos formulários, o usuário geral atual aparece primeiro com o rótulo visual “(você)”, sem alterar o nome persistido.
- Os filtros de Núcleos usam `router.replace`, reiniciam a paginação, preservam os demais parâmetros e sincronizam novamente a partir da URL em navegação voltar/avançar; a consulta Payload no servidor permanece a fonte dos resultados.
- A composição dos filtros usa uma única instância dos comboboxes oficiais. Atualizações rápidas derivam a próxima URL do estado controlado local, e a navegação canônica do servidor remonta a ilha pelo resultado de `buildNucleusFiltersKey`.
- O seletor de contato principal fixa o contato atual separadamente e retorna no máximo 99 alternativas quando ele existe (100 itens renderizados no total); a busca autenticada resolve o slug uma vez, restringe ao núcleo acessível e consulta somente lideranças engajadas.
- As opções de responsáveis nunca fazem parte do DTO da página do Núcleo: uma Server Action exclusiva de `geral` retorna apenas `{ id, name, isCurrent }` e `expectedUpdatedAt` ao abrir o diálogo; respostas obsoletas após fechamento/reabertura são ignoradas no cliente e a gravação continua protegida pela revisão e pelo lock existentes.
- Os diálogos lazy são controlados pelo shell que contém o gatilho persistente. Modos de estimativa mantêm um Root por gatilho para que Escape, overlay e X retornem ao botão exato; após sucesso com revalidação RSC, o modo de origem é transportado até a árvore atualizada para restaurar o foco.
- O carregamento dos módulos lazy compartilha somente uma pequena máquina de estados `idle|loading|ready|error`; cada shell conserva seu `import()` dinâmico e, após rejeição, fechar ou tentar novamente invalida a tentativa anterior para permitir um loader novo.
- O foco pós-sucesso da estimativa é condicionado aos dados atualizados (`proposedVoteEstimate` ou revisão de confirmação), usa refs dos gatilhos remontados e nunca timeout/RAF; quando o gatilho esperado não existe, o título focável do cartão recebe o foco.
- Advisory locks de runtime usam a sessão exata da transação Payload via `postgresTransactionLocks.ts`, com chaves textuais deduplicadas/ordenadas e namespaces independentes (`vote-estimate`, `nucleus-updates`, `primary-contact`, convites, telefone de contato e designação de coordenação). Leases de Consent permanecem exclusivamente em helpers de teste.
- A fronteira pública de convites exporta somente as três Server Actions; helpers privilegiados de SQL, autorização, token, consentimento e recuperação ficam em módulos `server-only`, com limites arquiteturais cobertos por teste.
- Em 2026-07-17, `Contact.city` passou a opcional porque Núcleos podem representar um Território de Identidade sem município/localidade; os fluxos públicos continuam exigindo cidade em seus próprios schemas. O cadastro de liderança mascara o celular no cliente, normaliza 11 dígitos no servidor e preserva valores/erros após falhas.
- Em 2026-07-17, decisão de produto: `Município` e `Bairro` do Núcleo passam a aceitar múltiplas entradas (arrays planos `cities`/`neighborhoods`), e `region` vira `regions` derivado no servidor a partir dos municípios, permitindo cruzar Territórios de Identidade. Bairros exigem município único. Modelo A (arrays planos) escolhido em vez de array estruturado por município. Plano: [`docs/plans/territorio-multi-municipio-bairro.md`](../../../docs/plans/territorio-multi-municipio-bairro.md); item do roadmap: A1.
- Em 2026-07-18, decisão de produto (revisão A2): no formulário de território, sugestões cruzadas **opt-in** via chips `{rótulo} +` (município/TI → união de ZEs faltantes; TI → municípios irmãos; ZE → municípios oficiais), em vez do auto-preenchimento forçado + Zonas TSE read-only da versão 2026-07-17 do plano. TI a partir do município continua derivado (A1). Cadastro estático município↔zona (`bahiaTseZones`) permanece. Plano: [`docs/plans/zonas-por-municipio.md`](../../../docs/plans/zonas-por-municipio.md); item do roadmap: A2.
- Em 2026-07-18, **A2 entregue e mesclado em `main`:** `src/lib/bahiaTseZones.ts` (TSE 2024 `detalhe_votacao_munzona` BA, fixture `bahia-tse-zones.official.json`, índices módulo `citiesByZone` / `zonesByTerritory`), `territorySuggestions.ts` (`buildTerritorySuggestions` com `outsideZones`), `TerritorySuggestionChips` + `NucleusTerritoryAndZonesFields` no formulário; `TseZoneInput` só controlado (`value`/`onChange`); aviso âmbar opcional para ZE fora do cadastro da geografia; alias `NucleusTerritoryFields` removido; sem migration.
- Em 2026-07-18, **B2 entregue (fundação de geometrias do mapa):** malhas IBGE qualidade intermediaria → TopoJSON versionado; TIs por `merge` da composição oficial (não shapefile IDE Bahia); extensão `*.topo.json`; reconciliação de nomes via `canonicalizeMunicipalityName`; script sem guard de banco; cleanup `/simplify` barato no mesmo PR; follow-ups de escala → B5.
- Em 2026-07-18, **A1 entregue:** `regions`/`cities`/`neighborhoods` como `text` + `hasMany` (tabela `electoral_nucleus_texts`); migration `20260718_190559_territorio_multi_municipio_bairro` com backfill; filtros da lista permanecem single-select na URL e consultam com `{ equals }` (associação ao array — não o operador substring `contains`); UI de `/campanha` com chips multi + bairros só com 1 município; dashboard e criação de liderança atualizados (`Contact.city` só quando `cities.length === 1`).
- O DTO paginado de atualizações contém somente filtro/paginação/feed; a visão geral chama um loader dedicado que busca `limit: 3` e apenas os autores necessários à prévia.
- A lista paginada de lideranças seleciona e serializa somente os campos da linha; avaliação interna e dados completos de contato são carregados apenas para a liderança selecionada. O fechamento usa `onCloseAutoFocus` no Sheet e `finalFocus` no Drawer, focaliza a linha de origem (ou o título do Núcleo) antes de navegar para a URL canônica, sem RAF/timeout.
- Em 2026-07-19, decisões de produto da Trilha E (mapa de projeção): **sem entidade nova por município** — `electoralNucleus` absorve a camada estratégica (metas, prioridade, dobradinhas) e a visão município-a-município é derivada de núcleos + baseline TSE agregados por `cities[]`; **série histórica 2014/2018 vem do TSE oficial** (seed A3 parametrizado por ano, só dep. federal turno 1 BA), não dos números da planilha; **lideranças/assessores da planilha entram como texto staff-only no import E4, nunca como `Contact`/`leadership`** (sem telefone nem consent — bloqueador LGPD da Onda 0 se aplica; o CRM real é alimentado depois pelo fluxo com Consent); tendência (Queda/Mantém/Aumento) é **derivada em leitura** (`computeVoteTrend`, limiares versionados), não persistida.
- Fonte: `/Users/francisco.solla/.cursor/plans/núcleos_eleitorais_mvp_7f788d29.plan.md`.
## Bloqueadores e próximas frentes
- **Bloqueador obrigatório de produção (PII real):** antes de lideranças/apoiadores reais ou import em massa, a assessoria jurídica eleitoral deve aprovar os textos definitivos (substituindo os provisórios do [Onda 0 MVP](../../../docs/plans/onda-0.md)). Os textos provisórios já sobem automaticamente via migration; o hold é de **titulares reais**, não de engenharia.
- Em 2026-07-17 o roadmap foi repriorizado orientado ao calendário eleitoral (Res. TSE 23.760/2026: propaganda a partir de 16/08, 1º turno 04/10), com ordem de execução, trilhas paralelas (A dados eleitorais/território, B superfícies de coordenação, C operação de campo, D plataforma) e grafo de dependências. Decisões de sequenciamento: lançar o MVP antes da migração multi-município; multi-município antes de zonas-por-municipio/eventos/demandas; baseline TSE independente de zonas-por-municipio (dependência rebaixada a suave); WhatsApp Business API movido a fora de escopo (vedação Meta + Res. 23.610 art. 33).
- Backlog consolidado do produto (admin RBAC, mapa, eventos, demandas, apoiadores, listas globais, site, white-label): [`docs/roadmap.md`](../../../docs/roadmap.md).