teqo-backup/docs/plans/insight-inteligencia-competitiva.md
Francisco Ignácio Fontoura Solla bcac665cb5 Ship /campanha nuclei MVP with RBAC, invites, and vote estimates.
Adds electoral nuclei, leaderships, updates, and WhatsApp invite flows behind campaign auth, plus the consolidated schema migration that Vercel applies on deploy.
2026-07-18 15:01:56 -03:00

66 lines
3.4 KiB
Markdown
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.

# Insight: inteligência competitiva (mais votado, ranking, margem)
Status: rascunho
Atualizado em: 2026-07-17
Item do roadmap: [docs/roadmap.md](../roadmap.md) (seção "Campanha → Próximos ciclos")
Responsável: —
## Contexto
Saber onde Solla foi bem é só metade; a outra é saber **quem o superou localmente** e por quanto. O baseline TSE 2022 (ver [baseline-eleitoral-tse.md](baseline-eleitoral-tse.md)) guarda o conjunto completo de candidatos por geografia, com flag de eleito — podemos dizer, por núcleo, quem foi o mais votado para deputado federal ali em 2022, qual a margem sobre Solla, e em que colocação Solla ficou. É inteligência competitiva: onde há adversário forte a desmontar e onde Solla já é o referencial.
## Objetivos
- Por núcleo, listar o top-N candidatos a dep. federal 2022 por votos nominais na geografia, com `elected` e partido/coligação.
- Destacar `winnerFederal` (mais votado), `sollaRank` (colocação de Solla) e `marginToWinner = winnerVotes − sollaVotes` (e `marginToElectable` quando aplicável).
- Exibir no detalhe do núcleo (aba overview) uma tabela compacta; no overview, agregar "núcleos onde Solla foi o mais votado" / "onde há adversário à frente".
## Decisões travadas
- **Leitura derivada** — sem escrita, sem `Consent`, sem migration.
- **Reusa** `electionCandidateVote` + `electionCandidate` (e `elected`).
- **Top-N configurável** (default 5) em `src/lib/electionInsights.ts`.
- Cargo principal: **deputado federal** (cargo do Solla). Estadual como secundário opcional.
## Questões em aberto
- Mostrar só candidatos com `elected=true` no top, ou todos os mais votados localmente? Recomendação: todos os mais votados localmente, com flag de eleito destacada.
- `lideranca` vê o competidor? Recomendação: sim (dado público).
- Cruzar com `runningAgain2026` (plano [insight-dobradinha-2026.md](insight-dobradinha-2026.md)) para marcar quem volta — adiar ao plano de dobradinha.
## Abordagem proposta
```mermaid
flowchart LR
Base["electionCandidateVote + electionCandidate<br/>agregados por geografia"]
Rank["ordenar por votos nominais<br/>+ flag elected"]
Calc["computeCompetitiveIntel(...)"]
Detail["Detalhe: tabela top-N<br/>+ winnerFederal + sollaRank + margem"]
Overview["Overview: núcleos onde Solla<br/>é o mais votado vs adversário à frente"]
Base --> Rank
Rank --> Calc
Calc --> Detail
Calc --> Overview
```
- **Helper** `src/lib/electionInsights.ts`: `computeCompetitiveIntel(candidateVotes, sollaNumber=1313, topN)` → `{ winner, sollaRank, marginToWinner, topCandidates[] }`.
- **Componente** `src/components/campaign/NucleusCompetitiveIntel.tsx` (server). Overview: bloco agregado no `NucleusListOverview`.
- **Teste int** cenários: Solla é o mais votado; Solla fora do top-N; `sollaVotes=0`.
## Arquivos a criar/alterar
- Criar: `src/components/campaign/NucleusCompetitiveIntel.tsx`.
- Alterar: `src/lib/electionInsights.ts`, `nucleos/[slug]/page.tsx` + `nucleusDetailPageData.ts`, overview da lista.
## Dependências
- [baseline-eleitoral-tse.md](baseline-eleitoral-tse.md) (`electionCandidateVote` + `electionCandidate` com `elected`).
## Não escopo
- Sugerir dobradinha (plano [insight-dobradinha-2026.md](insight-dobradinha-2026.md)) — aqui só exibimos o quadro competitivo, não sugerimos parceiros.
## Referências
- [baseline-eleitoral-tse.md](baseline-eleitoral-tse.md)
- AGENTS.md