Gate 2026-08-01: sem título de seção; geo só se permission granted; fatia em três entregáveis confirmada. Planos ready com Issue #N.
11 KiB
Empty state do wizard — chassis + ranking de esquecidos
Status: ready
Atualizado em: 2026-08-01
Issue: #92
Priority: P1
Model: composer-2.5
Impeccable: B — encaixe em WizardMunicipalitySearchStep (passo 1 dos wizards /campanha/acoes/<slug>)
Appetite: ~1–1,5 dia eng; modo suggest no home-search + rank puro + lista no idle; sem migration
Responsável: —
Design (Impeccable)
Âncoras: PRODUCT.md (Clarity under pressure; ação→local) / DESIGN.md (register product) · tema data-theme='campaign' · B60 WizardMunicipalitySearchStep · B68 HomeSearchHitRow / suggest · B59 CampaignWizardShell.
Na implementação (work-issue): craft compacto → critique → polish.
Brief compacto:
- Persona / contexto: assessor ou CG abre “Ajustar votos” / “Registrar sinal” no Início e cai no passo “Em qual município?” ainda sem digitar — hoje a região abaixo do input é deserto.
- Job principal: com zero teclas, ver municípios prováveis (esquecidos / frios no escopo) e avançar com um toque; digitar continua refinando via B60.
- Estratégia de cor: Restrained — mesmos hits do wizard; título de seção discreto; sem card.
- Edit where you see: não — descoberta/navegação de fluxo (select = auto-avanço B60).
- Anti-goals: mapa no empty; command palette; misturar hits de busca tipada com sugestões na mesma lista; motor E11 /
allocationDecisionneste passo; hero de KPI.
Wireframe (texto)
┌─ /campanha/acoes/<slug> (sem ?municipio=) ──────────────┐
│ [←] Ajustar votos [✕] │
│ Em qual município? │
│ ┌─ Buscar município ─────────────────────────────────┐ │
│ │ Nome do município… │ │
│ └────────────────────────────────────────────────────┘ │
│ · Cairu · Baixo Sul · 2022 … [alta?] │
│ · Valença · … │
│ · … (até ~8; select = avança com ?municipio=) │
└────────────────────────────────────────────────────────┘
Sem título de seção — mesma região de resultados da busca.
Continuity (B93) e geo (B94) entram depois como linhas prefixadas.
Dados → decisão → apresentação
- Vou apresentar dados? Sim — lista curta de municípios do escopo do ator, ranqueados por frescor + desempates operacionais.
- Decisões desbloqueadas:
- Assessor/CG: “em qual município desta carteira/estado eu executo esta ação agora, sem digitar o nome?”
- Implicação: atacar primeiro quem está frio (sem sinal) e, empate, quem a campanha já investiu mais / tem tendência / classe / volume de votos mais relevante.
- Forma escolhida: lista ranqueada (mesmo degrau B48/B60/B68 —
HomeSearchHitRow) — por quê a decisão é “qual abrir”. Rejeitado: mapa;CampaignMetricStrip; chart; chips sem readout (perda de contexto 2022 já no hit). - Profile: até ~8 itens (
HOME_SEARCH_SUGGEST_LIMIT/ paridade B68); scoped ao access; relativo/local (nome + TI + readout 2022 opcional); dias sem sinal como chave primária (não % estadual). - Anti-goals de dado: sem % estadual absoluto; sem gauge; sem inventar métrica nova além de reusar
lastSignalAt, E14, tendência, E10, votos 2022 já no scope/artifact.
Contexto
B60 ✓ entrega a etapa de busca de município nos wizards (WizardMunicipalitySearchStep + POST /campanha/home-search mode: 'wizard-municipality'). Com query inativa a região fica idle vazia — B60 adiou explicitamente “chips de recentes/prioritários”.
B68 ✓ resolveu o empty da busca do Início (mode: 'suggest', rank por papel: assessor = carteira fria; CG = prioritários alta × déficit). O wizard não consome esse modo: precisa de política própria (ação-primeiro, não omnibox) e de desempates que o pedido de produto (2026-08-01) nomeou: envolvimento (E14), tendência política, classe territorial (E10), número de votos.
Este item é o chassis + ranking server de esquecidos. Continuity (visitados / última ação) e geo ficam em B93 / B94.
Objetivos
- Quando
!query.isActiveno passo de município do wizard: preencher a mesma região de resultados com hits sugeridos (sem título de seção — decisão de produto 2026-08-01), não o deserto. - Novo modo tipado no
home-search(recomendação:mode: 'wizard-municipality-suggest') distinto desuggest(B68) e dewizard-municipality(B60 search) — política e payload próprios; staff-only (layoutacoes/já gateia). - Rank puro client-safe em
src/lib/(irmão dehomeSearchSuggest.ts), pinado em unit:- Primário: mais dias sem sinal primeiro (
lastSignalAtviaresolveMunicipalityLastSignalAt;null= mais frio). - Desempates (nesta ordem): envolvimento E14 (maior
engagementLevelRankprimeiro;null/Sem nívelpor último) → tendência (desfavoravel>neutra>favoravel>null) → classe E10 (territorialClassSortWeightdesc;sem_base/nullpor último) → votos 2022 do candidato no município (maior primeiro; sem série = por último) → nomept-BR.
- Primário: mais dias sem sinal primeiro (
- Cap ~8; access
overrideAccess: false; assessor nunca vê fora da carteira. - Digitar (≥ limiar B47) substitui sugestões pelos hits B60 (não misturar).
- Select =
wizardActionHref(auto-avanço intacto). - Sem migration / Consent / collection nova.
Decisões travadas
- Modo dedicado
wizard-municipality-suggest, não reusarsuggestdo Início. Wizard é ritual ação→local; B68 filtra CG apriority === 'alta'e usa déficit — aqui o pedido é esquecidos do escopo inteiro com desempates E14/tendência/classe/votos. Rejeitado: chamarloadHomeSearchSuggestionsno wizard (política errada); search comq=""(contradiz B66/B68). - Primário = frescor (
lastSignalAt), não sólastUpdateAt. Mesma semântica E9/B68 (max update × pledge). Rejeitado: sómunicipality.updatedAtdo Payload (ruído de admin); sólastUpdateAt(ignora pledges). - Desempates na ordem do pedido de produto (envolvimento → tendência → classe → votos), com pesos já existentes (
engagementLevelRank, ordem de tendência acima,territorialClassSortWeight, votos nominais 2022 do artifact/scope). Rejeitado: déficit de meta como desempate neste item (B68 já cobre no Início; misturar duas “inteligências” no mesmo empty confunde); LQ contínuo no lugar da classe. - Lista flat na região de resultados, sem título de seção (produto 2026-08-01). Reason labels por linha ficam para B93/B94 (neste slice todas as linhas são “esquecidos”). Rejeitado: heading “Prováveis”/“Sugestões”; cards; multi-grupo neste appetite.
- CG = escopo completo frio-primeiro (não filtrar a
priority === 'alta'). Prioridade alta continua só como indicador na linha. Rejeitado: copiar filtro B68 (política de omnibox, não de ritual). - Votos de desempate = nominais 2022 do candidato (artifact). Rejeitado: estimado central (live/cache).
- i18n / naming: identificadores
wizardMunicipalitySuggest,rankWizardMunicipalitySuggestions,loadWizardMunicipalitySuggestions; copy de empty tipado permanece a de B60.
Questões em aberto
- Nenhuma após gate 2026-08-01.
Abordagem proposta
flowchart LR
Idle["WizardMunicipalitySearchStep !query.isActive"] --> Suggest["POST home-search mode=wizard-municipality-suggest"]
Suggest --> Load["loadWizardMunicipalitySuggestions"]
Load --> Scope["loadMunicipalityScope + extraSelect"]
Scope --> Rank["rankWizardMunicipalitySuggestions"]
Rank --> Rows["HomeSearchHitRow + wizardActionHref"]
Type["query.isActive"] --> Search["mode=wizard-municipality B60"]
Componentes:
src/lib/wizardMunicipalitySuggest.ts(puro): input tipado (slug,name,lastSignalAt,engagementLevel,politicalTrend,territorialClass,votes2022) +rankWizardMunicipalitySuggestions(inputs, limit)+ constantes de ordem de tendência; unit-pinned.src/utilities/homeSearch/loadWizardMunicipalitySuggestions.ts(server-only):loadMunicipalityScopecomextraSelect(lastUpdateAt,engagementLevel,politicalTrend, …); classe via helper E10 já usado na lista/map; votos 2022 do artifact/bahiaElectionAggregates(ou campo já no scope se existir);overrideAccess: false.- Rota
home-search/route.ts+ schema zod discriminado: ramificar o novo mode; resposta no shapeWizardMunicipalitySearchSuccessResponse(ou irmão comresultKind: 'wizard-suggest'). WizardMunicipalitySearchStep: fetch suggest no idle; cancelar ao digitar; render hits na região de resultados (sem heading); empty tipado só quando search ativo e 0 hits.- Reuse:
HomeSearchHitRow,HomeSearchMunicipalityVoteTrailing,postCampaignJson,useHomeSearchQuery, copy emcampaignWizardCopy.ts. - Migration: Sem migration, sem collection, sem Consent.
Dependências
- Duras: nenhuma aberta (B59 ✓, B60 ✓).
- Soft: B68 ✓ (padrão suggest ≠ search); E9/E10/E14 ✓ (sinais de desempate); artifact TSE para votos 2022.
Não escopo
- Visitados recentes / última ação do ator → B93.
- Município mais próximo (geo) → B94.
- Empty da busca do Início (já B68); unificar políticas B68↔wizard.
- Motor E11 / fila de alocação no wizard.
- Leader (wizards são staff-only).
Rabbit holes
- Unificar
rankHomeSearchSuggestMunicipalitiese o rank do wizard num “suggest engine” genérico. Se alguém “só completar”: API parametrizada prematura. Mitigação: dois módulos puros até 3º call site (precedente depth check). - Carregar coverage/déficit/E11 no loader do wizard. Explode latência do idle. Mitigação: só campos de desempate listados; déficit fica no B68.
- Reason chips + multi-fonte neste PR. Mistura continuity/geo sem contrato de merge. Mitigação: B93/B94.
Adiado com gatilho
- Comparator compartilhado de frescor entre B68 e wizard. Revisitar no 3º call site (ledger O0+/DRY).
- RSC embed do suggest (evitar POST no mount do passo). Revisitar se latência idle for P1 em campo.
- Reason label “Sem atualização há N dias” na linha. Revisitar se craft/B93 pedir diferenciação visual além da ordem.
Referências
- GitHub Issue #92
WizardMunicipalitySearchStep.tsxhomeSearchSuggest.ts/loadHomeSearchSuggestions.tsbusca-municipio-wizard.md(B60 — adiados)sugestoes-busca-vazia-inicio.md(B68)engagementLevel.ts·territorialClassSortWeight.ts- AGENTS.md — access advisor;
overrideAccess: false; naming EN / copy pt-BR PRODUCT.md/DESIGN.md— Clarity under pressure; Field Desk