) : null}
+ {view.mobilization ? (
+
+ Mobilização:{' '}
+
+ {formatElectionNumber(view.mobilization.absoluteTotal)} votos possíveis
+
+ {' · '}
+
+ {view.mobilization.relativePercent}%
+ {' '}
+ do eleitorado apto
+ {' · '}
+
+ {formatElectionNumber(view.mobilization.brancosNulosTotal)} brancos/nulos
+
+ {' · '}
+
+ {formatElectionNumber(view.mobilization.abstencoesTotal)} abstenções
+
+
+ ) : null}
{view.leverage ? (
Alavancagem da chapa:{' '}
diff --git a/src/lib/electionInsights.ts b/src/lib/electionInsights.ts
index 9636f545..4fa379b7 100644
--- a/src/lib/electionInsights.ts
+++ b/src/lib/electionInsights.ts
@@ -81,6 +81,29 @@ export type ConversionBandDistribution = {
oportunidade: number
}
+export type MobilizationOpportunityStatus =
+ | 'opportunity'
+ | 'zero'
+ | 'semBaseline'
+ | 'semAptos'
+
+export type MobilizationOpportunityInput = {
+ abstencoes: number | null
+ brancos: number | null
+ nulos: number | null
+ aptos: number | null
+}
+
+export type MobilizationOpportunityResult = {
+ absolute: number
+ relative: number | null
+ abstencoes: number
+ brancosNulos: number
+ status: MobilizationOpportunityStatus
+ message: string
+ supportLine: string | null
+}
+
export type TerritorialClassificationBand =
| 'defesa'
| 'ataque'
@@ -119,6 +142,8 @@ const numberFormatter = new Intl.NumberFormat('pt-BR')
export const formatElectionNumber = (value: number): string => numberFormatter.format(value)
+const formatPercent = (ratio: number): number => Math.round(ratio * 100)
+
export const formatVoteTrendSeries = (series: VoteTrendSeries): string =>
`${formatElectionNumber(series.y2014)} (2014) → ${formatElectionNumber(series.y2018)} (2018) → ${formatElectionNumber(series.y2022)} (2022)`
@@ -241,6 +266,10 @@ export const territorialClassAlertVariant = (
export const conversionRateAlertVariant = (band: ConversionRateBand): 'default' | 'pending' =>
band === 'oportunidade' ? 'pending' : 'default'
+export const isComparableMobilization = (
+ status: MobilizationOpportunityStatus,
+): status is 'opportunity' => status === 'opportunity'
+
type TrendPair = { fromVotes: number; toVotes: number; fromYear: number; toYear: number }
const trendPairsByPriority = (series: VoteTrendSeries): TrendPair[] => [
@@ -456,6 +485,67 @@ export const computeConversionRate = ({
}
}
+/**
+ * Sum abstentions + blank + null votes as mobilization potential (excludes anulados).
+ */
+export const computeMobilizationOpportunity = ({
+ abstencoes,
+ brancos,
+ nulos,
+ aptos,
+}: MobilizationOpportunityInput): MobilizationOpportunityResult => {
+ if (aptos === null) {
+ return {
+ absolute: 0,
+ relative: null,
+ abstencoes: 0,
+ brancosNulos: 0,
+ status: 'semBaseline',
+ message: NO_ELECTION_BASELINE_MESSAGE,
+ supportLine: null,
+ }
+ }
+
+ if (aptos <= 0) {
+ return {
+ absolute: 0,
+ relative: null,
+ abstencoes: 0,
+ brancosNulos: 0,
+ status: 'semAptos',
+ message: 'Sem eleitores aptos no baseline para esta geografia',
+ supportLine: null,
+ }
+ }
+
+ const abstencoesTotal = abstencoes ?? 0
+ const brancosNulos = (brancos ?? 0) + (nulos ?? 0)
+ const absolute = abstencoesTotal + brancosNulos
+ const relative = absolute / aptos
+
+ if (absolute <= 0) {
+ return {
+ absolute: 0,
+ relative: 0,
+ abstencoes: abstencoesTotal,
+ brancosNulos,
+ status: 'zero',
+ message: 'Sem potencial de mobilização no baseline 2022',
+ supportLine: 'Sem brancos, nulos ou abstenções no baseline 2022',
+ }
+ }
+
+ return {
+ absolute,
+ relative,
+ abstencoes: abstencoesTotal,
+ brancosNulos,
+ status: 'opportunity',
+ message: 'Oportunidade de mobilização',
+ supportLine: `${formatElectionNumber(brancosNulos)} brancos/nulos + ${formatElectionNumber(abstencoesTotal)} abstenções = ${formatElectionNumber(absolute)} votos possíveis · ${formatPercent(relative)}% do eleitorado apto`,
+ }
+}
+
export type TicketLeverageStatus =
| 'comparable'
| 'noEstimate'
@@ -522,7 +612,12 @@ export type TicketFlipOverviewAggregate = {
bothAlignedCount: number
}
-const formatPercent = (ratio: number): number => Math.round(ratio * 100)
+export type MobilizationOverviewAggregate = {
+ absoluteTotal: number
+ relativePercent: number
+ brancosNulosTotal: number
+ abstencoesTotal: number
+}
/** User-facing label for the configured majoritarian ticket base (cycle-specific names). */
export const formatMajoritarianTicketBaseLabel = (): string =>
@@ -776,6 +871,20 @@ export const aggregateTicketFlipOverview = (
return { count, bothAlignedCount }
}
+export const aggregateMobilizationOverview = (
+ input: MobilizationOpportunityInput,
+): MobilizationOverviewAggregate | null => {
+ const result = computeMobilizationOpportunity(input)
+ if (!isComparableMobilization(result.status)) return null
+
+ return {
+ absoluteTotal: result.absolute,
+ relativePercent: formatPercent(result.relative ?? 0),
+ brancosNulosTotal: result.brancosNulos,
+ abstencoesTotal: result.abstencoes,
+ }
+}
+
export const ticketLeverageAlertVariant = (
leverage: TicketLeverageResult,
): 'default' | 'pending' =>
diff --git a/src/utilities/nucleusElectoralBaseline.ts b/src/utilities/nucleusElectoralBaseline.ts
index 65e9d330..fa25e9c3 100644
--- a/src/utilities/nucleusElectoralBaseline.ts
+++ b/src/utilities/nucleusElectoralBaseline.ts
@@ -18,6 +18,7 @@ import {
aggregateTicketFlipOverview,
aggregateTicketLeverageOverview,
aggregateVoteTrend,
+ aggregateMobilizationOverview,
computeConversionRate,
computeGapVs2022,
computeTerritorialClass,
@@ -25,6 +26,8 @@ import {
computeTicketLeverage,
isComparableConversionBand,
isComparableTerritorialClass,
+ type MobilizationOverviewAggregate,
+ type MobilizationOpportunityInput,
type ConversionBandDistribution,
type ConversionRateBand,
type TerritorialClassificationBand,
@@ -389,10 +392,15 @@ const aggregateElectorate = (
const sumFederalTallyForGeography = (
talliesByCityZone: ReadonlyMap,
geography: NucleusElectionGeography,
-): Pick => {
+): Pick<
+ NucleusElectoralBaselineViewModel['electorate'],
+ 'aptos' | 'abstencoes' | 'validos' | 'brancos' | 'nulos'
+> => {
let aptos = 0
let abstencoes = 0
let validos = 0
+ let brancos = 0
+ let nulos = 0
for (const { cityName, zoneNumber } of geography.cityZonePairs) {
const row = talliesByCityZone.get(cityZoneKey(cityName, zoneNumber))
@@ -400,9 +408,11 @@ const sumFederalTallyForGeography = (
aptos += row.aptos
abstencoes += row.abstencoes
validos += row.votosValidos
+ brancos += row.votosBranco
+ nulos += row.votosNulo
}
- return { aptos, abstencoes, validos }
+ return { aptos, abstencoes, validos, brancos, nulos }
}
export const aggregateNucleusElectoralBaseline = (
@@ -800,6 +810,7 @@ export type NucleusListElectionOverview = {
baseline2022: NucleusBaseline2022OverviewAggregate | null
trend: NucleusTrendOverviewAggregate | null
conversion: NucleusConversionOverviewAggregate | null
+ mobilization: MobilizationOverviewAggregate | null
leverage: TicketLeverageOverviewAggregate | null
flipOpportunity: TicketFlipOverviewAggregate | null
classification: NucleusClassificationOverviewAggregate | null
@@ -823,6 +834,7 @@ export const loadNucleusListElectionOverview = async (
baseline2022: null,
trend: null,
conversion: null,
+ mobilization: null,
leverage: null,
flipOpportunity: null,
classification: null,
@@ -841,6 +853,7 @@ export const loadNucleusListElectionOverview = async (
baseline2022: null,
trend: null,
conversion: null,
+ mobilization: null,
leverage: null,
flipOpportunity: null,
classification: null,
@@ -866,12 +879,29 @@ export const loadNucleusListElectionOverview = async (
)
const classificationBands: TerritorialClassificationBand[] = []
+ const federalTallyByIndex = new Map<
+ number,
+ ReturnType
+ >()
+ const mobilizationInput: MobilizationOpportunityInput = {
+ aptos: 0,
+ abstencoes: 0,
+ brancos: 0,
+ nulos: 0,
+ }
+
for (const index of withGeographyIndexes) {
const geography = geographies[index]!
- const { validos } = sumFederalTallyForGeography(classificationTalliesByCityZone, geography)
+ const tallies = sumFederalTallyForGeography(classificationTalliesByCityZone, geography)
+ federalTallyByIndex.set(index, tallies)
+ mobilizationInput.aptos = (mobilizationInput.aptos ?? 0) + tallies.aptos
+ mobilizationInput.abstencoes = (mobilizationInput.abstencoes ?? 0) + tallies.abstencoes
+ mobilizationInput.brancos = (mobilizationInput.brancos ?? 0) + tallies.brancos
+ mobilizationInput.nulos = (mobilizationInput.nulos ?? 0) + tallies.nulos
+
const territorial = computeTerritorialClass({
sollaVotes: sumCandidateVotesForGeography(geography, votes2022),
- federalValidVotes: validos,
+ federalValidVotes: tallies.validos,
})
if (isComparableTerritorialClass(territorial.band)) {
classificationBands.push(territorial.band)
@@ -883,6 +913,8 @@ export const loadNucleusListElectionOverview = async (
? { distribution: aggregateTerritorialClass(classificationBands) }
: null
+ const mobilization = aggregateMobilizationOverview(mobilizationInput)
+
const flipResults = await Promise.all(
withGeographyIndexes.map(async (index) => {
const geography = geographies[index]!
@@ -897,6 +929,7 @@ export const loadNucleusListElectionOverview = async (
baseline2022: { gapTotal: null, above: 0, below: 0 },
trend,
conversion: null,
+ mobilization,
leverage: null,
flipOpportunity,
classification,
@@ -928,10 +961,10 @@ export const loadNucleusListElectionOverview = async (
comparableCount += 1
}
- const { aptos, abstencoes } = sumFederalTallyForGeography(
- classificationTalliesByCityZone,
- geography,
- )
+ const tallies = federalTallyByIndex.get(index)
+ if (!tallies) continue
+
+ const { aptos, abstencoes } = tallies
const conversion = computeConversionRate({
aptos,
abstencoes,
@@ -970,6 +1003,7 @@ export const loadNucleusListElectionOverview = async (
},
trend,
conversion,
+ mobilization,
leverage: aggregateTicketLeverageOverview(leverageRows),
flipOpportunity,
classification,
diff --git a/src/utilities/nucleusListOverviewPageData.ts b/src/utilities/nucleusListOverviewPageData.ts
index e8099ce5..a93af921 100644
--- a/src/utilities/nucleusListOverviewPageData.ts
+++ b/src/utilities/nucleusListOverviewPageData.ts
@@ -176,6 +176,7 @@ export const loadNucleusListOverviewData = async (
baseline2022: listElectionOverview.baseline2022,
trend: listElectionOverview.trend,
conversion: listElectionOverview.conversion,
+ mobilization: listElectionOverview.mobilization,
leverage: listElectionOverview.leverage,
flipOpportunity: listElectionOverview.flipOpportunity,
classification: listElectionOverview.classification,
diff --git a/src/utilities/nucleusListOverviewViewModels.ts b/src/utilities/nucleusListOverviewViewModels.ts
index 639b621b..a8cf814d 100644
--- a/src/utilities/nucleusListOverviewViewModels.ts
+++ b/src/utilities/nucleusListOverviewViewModels.ts
@@ -1,5 +1,5 @@
import type { NucleusPriority } from '@/lib/schemas/nucleus'
-import type { TicketFlipOverviewAggregate, TicketLeverageOverviewAggregate } from '@/lib/electionInsights'
+import type { TicketFlipOverviewAggregate, TicketLeverageOverviewAggregate, MobilizationOverviewAggregate } from '@/lib/electionInsights'
import type { CampaignUser, NucleusUpdate } from '@/payload-types'
import type { ActionPlanUpcomingPreviewRecord } from '@/utilities/actionPlanUpcomingPreview'
import type {
@@ -61,6 +61,8 @@ export type NucleusListOverviewViewModel = {
trend: NucleusTrendOverviewAggregate | null
/** Null when no comparable nucleus has aptos + confirmed estimate. */
conversion: NucleusConversionOverviewAggregate | null
+ /** Null when the filtered set has no mobilization potential in baseline tallies. */
+ mobilization: MobilizationOverviewAggregate | null
/** Null when no comparable nucleus has ticket votes + confirmed estimate. */
leverage: TicketLeverageOverviewAggregate | null
/** Null when no nucleus in the filtered set has resolvable TSE geography. */
@@ -83,6 +85,7 @@ export const buildNucleusListOverviewViewModel = ({
baseline2022 = null,
trend = null,
conversion = null,
+ mobilization = null,
leverage = null,
flipOpportunity = null,
classification = null,
@@ -95,6 +98,7 @@ export const buildNucleusListOverviewViewModel = ({
baseline2022?: NucleusBaseline2022OverviewAggregate | null
trend?: NucleusTrendOverviewAggregate | null
conversion?: NucleusConversionOverviewAggregate | null
+ mobilization?: MobilizationOverviewAggregate | null
leverage?: TicketLeverageOverviewAggregate | null
flipOpportunity?: TicketFlipOverviewAggregate | null
classification?: NucleusClassificationOverviewAggregate | null
@@ -134,6 +138,7 @@ export const buildNucleusListOverviewViewModel = ({
highPriorityCount,
trend,
conversion,
+ mobilization,
leverage,
flipOpportunity,
classification,
diff --git a/tests/int/nucleusListElectionOverview.int.spec.ts b/tests/int/nucleusListElectionOverview.int.spec.ts
index c8c666de..3cb0f5de 100644
--- a/tests/int/nucleusListElectionOverview.int.spec.ts
+++ b/tests/int/nucleusListElectionOverview.int.spec.ts
@@ -134,6 +134,7 @@ describe('loadNucleusListElectionOverview (E7 F2)', () => {
baseline2022: null,
trend: null,
conversion: null,
+ mobilization: null,
leverage: null,
flipOpportunity: null,
classification: null,
diff --git a/tests/unit/electionInsights.unit.spec.ts b/tests/unit/electionInsights.unit.spec.ts
index ea632665..641b1ebd 100644
--- a/tests/unit/electionInsights.unit.spec.ts
+++ b/tests/unit/electionInsights.unit.spec.ts
@@ -4,16 +4,19 @@ import { describe, expect, it } from 'vitest'
import {
aggregateConversionBand,
+ aggregateMobilizationOverview,
aggregateTerritorialClass,
aggregateVoteTrend,
comparableTrendCount,
computeConversionRate,
computeGapVs2022,
+ computeMobilizationOpportunity,
computeTerritorialClass,
computeVoteTrend,
CONVERSION_OPPORTUNITY_MAX,
CONVERSION_REDUTO_MIN,
isComparableConversionBand,
+ isComparableMobilization,
type GapVs2022Baseline,
TERRITORIAL_ATAQUE_MIN,
TERRITORIAL_DEFESA_MIN,
@@ -194,6 +197,88 @@ describe('isComparableConversionBand', () => {
})
})
+describe('computeMobilizationOpportunity', () => {
+ it('matches the design-ref subtotals and total', () => {
+ expect(
+ computeMobilizationOpportunity({
+ abstencoes: 680,
+ brancos: 100,
+ nulos: 42,
+ aptos: 4700,
+ }),
+ ).toMatchObject({
+ absolute: 822,
+ brancosNulos: 142,
+ abstencoes: 680,
+ status: 'opportunity',
+ message: 'Oportunidade de mobilização',
+ supportLine:
+ '142 brancos/nulos + 680 abstenções = 822 votos possíveis · 17% do eleitorado apto',
+ })
+ })
+
+ it('reports semAptos when aptos is zero', () => {
+ expect(
+ computeMobilizationOpportunity({ abstencoes: 10, brancos: 5, nulos: 2, aptos: 0 }),
+ ).toMatchObject({
+ status: 'semAptos',
+ absolute: 0,
+ })
+ })
+
+ it('reports zero when all components are absent', () => {
+ expect(
+ computeMobilizationOpportunity({ abstencoes: 0, brancos: 0, nulos: 0, aptos: 1000 }),
+ ).toMatchObject({
+ status: 'zero',
+ absolute: 0,
+ })
+ })
+
+ it('reports semBaseline when aptos is null', () => {
+ expect(
+ computeMobilizationOpportunity({ abstencoes: 10, brancos: 5, nulos: 2, aptos: null }),
+ ).toMatchObject({
+ status: 'semBaseline',
+ absolute: 0,
+ })
+ })
+})
+
+describe('isComparableMobilization', () => {
+ it('accepts only opportunity', () => {
+ expect(isComparableMobilization('opportunity')).toBe(true)
+ expect(isComparableMobilization('zero')).toBe(false)
+ })
+})
+
+describe('aggregateMobilizationOverview', () => {
+ it('maps comparable opportunity to overview fields', () => {
+ expect(
+ aggregateMobilizationOverview({
+ abstencoes: 680,
+ brancos: 100,
+ nulos: 42,
+ aptos: 4700,
+ }),
+ ).toEqual({
+ absoluteTotal: 822,
+ relativePercent: 17,
+ brancosNulosTotal: 142,
+ abstencoesTotal: 680,
+ })
+ })
+
+ it('returns null when there is no mobilization potential', () => {
+ expect(
+ aggregateMobilizationOverview({ abstencoes: 0, brancos: 0, nulos: 0, aptos: 1000 }),
+ ).toBeNull()
+ expect(
+ aggregateMobilizationOverview({ abstencoes: 10, brancos: 5, nulos: 2, aptos: null }),
+ ).toBeNull()
+ })
+})
+
describe('computeTerritorialClass', () => {
it('classifies defesa at 35% of valid votes', () => {
const validos = 2490