Document derived Censo-based electorate profile alongside existing manual voterProfiles in the nucleus Eleitorado tab.
9.2 KiB
Perfis do eleitorado — perfil médio IBGE + manuais
Status: rascunho Atualizado em: 2026-07-19 Item do roadmap: docs/roadmap.md (Trilha A, item A8) Responsável: —
Contexto
A aba Eleitorado do detalhe do núcleo (ElectorateContent em src/components/campaign/NucleusActiveTab.tsx, só staff) já persiste perfis manuais no array electoralNucleus.voterProfiles (label, ageRange, incomeBand, occupation, localTraits, notes) — edição via NucleusIntelligenceDialog. Hoje a lista começa vazia; o empty state diz que perfis “serão trabalhados na próxima etapa”.
A oportunidade (decisão de produto 2026-07-19): usar dados agregados públicos do IBGE (Censo 2022 e tabelas relacionadas) para derivar um perfil médio/comum do território do núcleo a partir de cities[], exibi-lo como cartão distinto, e continuar permitindo perfis manuais adicionais (já existentes). Isso dá um ponto de partida honesto para a coordenação sem forçar cadastro à mão, e sem inventar um cadastro paralelo de “pessoa” — é inteligência territorial, não CRM.
Já temos o join estável município → código IBGE 7 dígitos em src/lib/bahiaMunicipalityCodes.ts (B2) e a geografia multi-município em cities[] (A1).
Objetivos
- Importar (CLI, estático) indicadores demográficos municipais BA suficientes para montar um “perfil médio” legível (idade dominante, sexo, renda, escolaridade/ocupação quando a tabela cobrir).
- Derivar em leitura o perfil do núcleo a partir de
cities[](média ponderada pela população quando houver >1 município; sóregions→ união das cidades do TI viacitiesForTerritory). - Exibir o perfil calculado na aba Eleitorado, claramente marcado como Calculado (IBGE), separado dos manuais.
- Manter CRUD de
voterProfilesmanuais; opcionalmente oferecer “Adicionar como perfil” (copia o calculado para o array, editável depois). - Guardrails: dado público agregado (sem PII, sem
Consent); access só staff (mesmo escopo da aba Eleitorado hoje); sem chamada HTTP ao IBGE em runtime de request;overrideAccess: falsenas leituras de núcleo.
Decisões travadas
- Perfil calculado é derivado em leitura, não sobrescreve
voterProfiles. Persistir no array misturaria fonte IBGE com edição humana e apagaria trabalho do coordenador em re-seed. O cartão IBGE é view model; o array continua 100% manual. - Dado estático versionado no repo (padrão B2/
bahiaTseZones/bahiaMunicipalityCodes), não collection Payload nem fetch SIDRA por request. Script re-executável baixa Agregados/SIDRA (ou CSV oficial), emitesrc/lib/bahiaMunicipalityDemographics.ts(+ fixture). Sem migration, semConsent, sem revalidate (páginas de campanha dinâmicas). - Granularidade município. Núcleo indexa
cities[]; bairro/seção não têm série IBGE estável alinhada ao app. Multi-cidade = ponderação por população residente do Censo. - Sem geografia → estado “sem perfil IBGE” (mesmo espírito do baseline TSE sem território).
- v1 cobre BA, Censo 2022 (e tabelas de rendimento/trabalho já divulgadas no mesmo ciclo). Séries antigas (2010) e PNAD contínua ficam fora.
- i18n e naming (AGENTS.md): identificadores em inglês (
bahiaMunicipalityDemographics,getNucleusIbgeVoterProfile,ComputedVoterProfileViewModel); strings visíveis em pt-BR (“Perfil médio do território”, “Calculado (IBGE Censo 2022)”).
Questões em aberto
- Quais indicadores entram no cartão v1? Faixa etária modal + % sexo + renda domiciliar per capita (ou faixa) + cor/raça dominante são o mínimo útil e mapam bem aos campos já existentes (
ageRange/incomeBand). Ocupação formal (RAIS) é outra fonte. Recomendação: v1 = população + pirâmide etária resumida (3–4 faixas) + sexo + rendimento;occupation/localTraitssó no manual ou numa linha “destaque” textual gerada se houver variável estável; definir tabelas SIDRA exatas na implementação e documentar no cabeçalho do módulo. liderancavê o perfil IBGE? Hoje a aba Eleitorado redirecionaliderancapara overview. Recomendação: manter staff-only na v1 (dado agregado público, mas a superfície de inteligência já é staff); reavaliar com produto se quiserem kit de campo para liderança.- Texto gerado vs. só números? Um parágrafo (“Predominam adultos 30–59, renda …”) ajuda o empty state; números sozinhos evitam tom “científico” falso. Recomendação: números + 1 linha de síntese template (constantes versionadas), sem LLM.
- Copiar para
voterProfiles? Recomendação: botão opt-in “Usar como perfil manual” na aba (Server Action que faz append de um item pré-preenchido); nunca auto-append no load.
Abordagem proposta
flowchart LR
SIDRA["IBGE Agregados / SIDRA<br/>Censo 2022 BA N6"]
Script["scripts/build-bahia-demographics.mjs<br/>pnpm build:demographics"]
Static["bahiaMunicipalityDemographics.ts<br/>codarea → indicadores"]
Nuc["electoralNucleus.cities[]"]
Codes["bahiaMunicipalityCodes<br/>nome → codarea"]
Derive["getNucleusIbgeVoterProfile<br/>ponderado por população"]
UI["Aba Eleitorado:<br/>card Calculado + cards manuais"]
Manual["voterProfiles[]<br/>NucleusIntelligenceDialog"]
SIDRA --> Script --> Static
Nuc --> Codes --> Derive
Static --> Derive --> UI
Manual --> UI
Componentes:
bahiaMunicipalityDemographics(src/lib/bahiaMunicipalityDemographics.ts): mapacodarea→{ population, ageBands, sexShare, incomeBand, … }+ helpersdemographicsForCode/demographicsForMunicipalityName. Cabeçalho com URL + SHA-256 dos downloads (padrãobahiaMunicipalityCodes).getNucleusIbgeVoterProfile(src/utilities/nucleusIbgeVoterProfile.ts,server-only): entrada{ cities, regions }→ComputedVoterProfileViewModel | { status: 'semPerfil' }. Resolve cidades efetivas (citiesoucitiesForTerritorydebahiaTerritories.ts); pondera indicadores; formatalabelfixo (“Perfil médio do território”) + campos alinhados ao schema manual para a UI e para o opt-in de cópia.ElectorateContent(NucleusActiveTab.tsx): acima dos manuais, cardNucleusIbgeVoterProfile(novo, PascalCase) com badge “Calculado (IBGE)”; empty state só quando não há calculado nem manuais; atualizar copy (“nenhum perfil cadastrado” → distinguir ausência de IBGE vs. ausência de manuais).NucleusIntelligenceDialog: sem mudança obrigatória no schema; opcionalmente botão/ação “Adicionar perfil a partir do IBGE” que pré-preenche umEditableProfileno estado cliente (ou Server Action de append).- Script
scripts/build-bahia-demographics.mjs(pnpm build:demographics): baixa Agregados para os 417 municípios BA; reusadownloadToBuffer/ cache sobdata/demographics/(gitignored); não toca banco (semassertLocalDatabase). Fora depnpm build/pnpm dev. - Testes: unit do ponderador (1 cidade, 2 cidades, sem geografia, município sem row); int de cobertura 417
codareavsbahiaMunicipalityCodes+ fixturetests/fixtures/bahia-municipality-demographics.official.json. - Migration: nenhuma. Sem collection nova. Sem Consent. Server Action só se o opt-in de cópia for mutação dedicada (senão reusa o update de inteligência existente).
Dependências
- Dura: A1 Território multi-município/bairro ✓ —
cities[]/regions[]ecitiesForTerritory. - Suave: B2 ✓ —
bahiaMunicipalityCodes/codeForMunicipality(sem isso o script teria que reimplementar o join nome→codarea). - Nenhuma dependência de A3/A4 — fonte IBGE ≠ TSE; o baseline de votos e o perfil demográfico convivem na mesma ficha sem acoplamento de dados.
- Reusa:
voterProfiles+NucleusIntelligenceDialog+ aba Eleitorado staff-only; padrão de artefato estático de B2.
Não escopo
- Microdados IBGE / perfilamento de indivíduos (LGPD; fora de escopo absoluto).
- Perfil por bairro/seção (sem série alinhada; E5 cobre Salvador por bairro no eixo eleitoral TSE, não demográfico).
- Insights de voto A5 (conversão, classificação, alavancagem…) — planos
insight-*.md. - Camada demográfica no mapa Leaflet (B3) — eventual follow-up se o coroplético quiser densidade/renda.
- PNAD contínua, RAIS/CAGED, Estimativas anuais pós-2022 — fase futura se o Censo 2022 cobrir o ciclo.
- Abrir a aba Eleitorado para
lideranca(mudança de access à parte).
Referências
docs/roadmap.md(Trilha A, item A8; Janela 3)src/collections/ElectoralNucleus.ts— campovoterProfilessrc/components/campaign/NucleusActiveTab.tsx—ElectorateContent(staff-only)src/components/campaign/NucleusIntelligenceDialog.tsx— editor manualsrc/lib/schemas/nucleus.ts—voterProfileSchemasrc/lib/bahiaMunicipalityCodes.ts— join IBGEsrc/lib/bahiaTerritories.ts—citiesForTerritorydocs/plans/mapa-bahia-geometrias.md— precedente de artefato estático + script CLIdocs/plans/baseline-eleitoral-tse.md— precedente de dado público agregado (TSE; fonte distinta)- IBGE API Agregados: https://servicodados.ibge.gov.br/api/v3/agregados
- IBGE SIDRA: https://apisidra.ibge.gov.br/
- AGENTS.md — naming EN/pt-BR; Campaign auth; sem PII; padrão estático B2