teqo-backup/docs/plans/wizard-municipio-sugestoes-chassis.md
Cursor Agent c53add3f8f
docs: registra B92–B94 (Issues #92–#94) pós-gate
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.
2026-08-01 06:57:30 +00:00

11 KiB
Raw Blame History

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 / allocationDecision neste 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.isActive no 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 de suggest (B68) e de wizard-municipality (B60 search) — política e payload próprios; staff-only (layout acoes/ já gateia).
  • Rank puro client-safe em src/lib/ (irmão de homeSearchSuggest.ts), pinado em unit:
    1. Primário: mais dias sem sinal primeiro (lastSignalAt via resolveMunicipalityLastSignalAt; null = mais frio).
    2. Desempates (nesta ordem): envolvimento E14 (maior engagementLevelRank primeiro; null/Sem nível por último) → tendência (desfavoravel > neutra > favoravel > null) → classe E10 (territorialClassSortWeight desc; sem_base/null por último) → votos 2022 do candidato no município (maior primeiro; sem série = por último) → nome pt-BR.
  • 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 reusar suggest do Início. Wizard é ritual ação→local; B68 filtra CG a priority === 'alta' e usa déficit — aqui o pedido é esquecidos do escopo inteiro com desempates E14/tendência/classe/votos. Rejeitado: chamar loadHomeSearchSuggestions no wizard (política errada); search com q="" (contradiz B66/B68).
  • Primário = frescor (lastSignalAt), não só lastUpdateAt. Mesma semântica E9/B68 (max update × pledge). Rejeitado: só municipality.updatedAt do 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): loadMunicipalityScope com extraSelect (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 shape WizardMunicipalitySearchSuccessResponse (ou irmão com resultKind: '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 em campaignWizardCopy.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 rankHomeSearchSuggestMunicipalities e 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