fsolla/teqo-backup
1
0
Fork 0
mirror of https://github.com/fsolla/teqo.git synced 2026-11-13 15:13:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
teqo-backup/docs/plans/wizard-mudar-tendencia.md

9 KiB
Raw Permalink Blame History

Wizard mudar tendência — escolher destino + justificativa

Status: entregue (2026-07-30) Atualizado em: 2026-07-30 Item do roadmap: docs/roadmap.md (Trilha B, item B64 — UX-1 wizards) Impeccable: C — UI nova (grid de tendências coloridas + Drawer de info + passo de justificativa) Appetite: ~1–1,25 dia eng; 2 etapas no B59; write via POST /campanha/municipios/political-trend / action B24 ✓ Responsável: —

Design (Impeccable)

Âncoras: PRODUCT.md / DESIGN.md · Drawer shadcn · tema campaign · badges politicalTrendBadgeVariant / tokens estimate-confirmed · sibling visual B63.

Na implementação: shape → craft → critique → polish.

Brief compacto:

  • Persona: CG/assessor no polegar; acabou de registrar sinal ou ajustar votos e precisa fechar a leitura de tendência — ou veio direto do botão “Mudar tendência” do Início.
  • Job principal: escolher a nova tendência (não a atual) em 1 toque, justificar o porquê (pré-preenchido quando veio de outro fluxo), ou pular a mudança sem travar o fluxo pai.
  • Estratégia de cor: tiles com fundo branco + borda/ícone/título na cor da tendência (favorável → verde estimate-confirmed-foreground; neutra → neutro/secondary; desfavorável → destructive). Diferente do B63 (transparente + borda cinza): aqui a cor é o significado.
  • Edit where you see: não — fluxo com Salvar explícito no passo de justificativa (exceção de nota/confirmação).
  • Anti-goals: select nativo; oferecer a tendência atual como opção; auto-save silencioso estilo B24 neste wizard; cards elevados / Signal Red decorativo no idle; forçar mudança quando o fluxo veio de votos/sinal.

Dados → decisão → apresentação

Dados: N/A como métrica — status categórico + texto livre. Decisão = mover a tendência política do município e gravar o porquê, ou pular.

Contexto

Ação A3 do Início (fluxos-acao-primeiro-inicio.md) e passo “Quer mudar a tendência?” embutido em A1. Catálogo B45 ✓ já tem change-trend. Escrita já existe (B24 ✓): MunicipalityListTrendControl → POST /campanha/municipios/political-trend + municipalityPoliticalTrendSchema (status + note).

Pedido (2026-07-29):

Etapa 1 — escolher tendência

  • Título da tela = estado atual, ex. “Tendência Favorável” (se status nulo: “Tendência não registrada”).
  • Botões = mesmo chassis de tile do B63 (quadrado grande, cantos arredondados, ícone canto superior esquerdo, Info canto superior direito → bottom Drawer), mas:
    • fundo branco;
    • cor e borda relativas à tendência alvo;
    • título = label (Favorável / Neutra / Desfavorável);
    • descrição abaixo do título = “Mudar tendência para X” (X = mesmo label).
  • Mostrar apenas tendências ≠ atual (se atual nula, mostrar as três).
  • Topo direito: “Pular mudança de tendência →” (sempre — nas duas etapas).

Etapa 2 — justificativa

  • Textarea; se o wizard veio embutido de outro fluxo, pré-preencher a nota, ex.:
    • "Sinal de invasão: <descrição do sinal>"
    • "Ajuste de votos: <valor anterior> → <novo valor>"
    • (outros orquestradores: mesma fábrica de string)
  • Botão “Limpar” zera o texto de uma vez.
  • Botão “Salvar” grava a mudança (status escolhido + nota).
  • “Pular mudança de tendência →” permanece no topo direito.

Município: já escolhido (B60) ou pré-preenchido se veio embutido de A1/A2.

Objetivos

  • Duas telas/passos no shell B59: WizardTrendChoiceStep + WizardTrendNoteStep.
  • Catálogo de tiles: mapear politicalTrendStatuses → ícone Lucide + label (politicalTrendLabels) + infoContent (o que significa / quando usar) + classes de borda/texto por status.
  • Info: botão Info com stopPropagation (não seleciona a tendência).
  • Select de tendência = avança para o passo de nota (sem CTA intermediário).
  • Skip: trailing do B59 → próximo bloco do fluxo pai ou Início; sempre visível (diferente do B63, que esconde skip no entry register-signal).
  • Prefill: helper puro client-safe buildPoliticalTrendNotePrefill(source) em lib/ (discriminated union: signal | voteAdjustment | custom | none).
  • Limpar: setNote('') imediato (sem confirm).
  • Salvar: reusar setMunicipalityPoliticalTrend / endpoint B24 com overrideAccess: false; pending no botão (Feel the action); nota obrigatória se o status muda (alinhar ao rascunho A3 — “por quê obrigatório se mudou”).
  • Sem migration / Consent (campos já existem).
  • Unit: filtra tendência atual; prefill templates; Limpar; skip sempre montado; info não seleciona.

Decisões travadas

  • Duas etapas (escolha → justificativa), um item de roadmap. Rejeitado: IDs separados; quatro passos do rascunho A3 antigo (município = B60; commit = Salvar nesta etapa).
  • Skip sempre visível nas duas etapas. Rejeitado: espelhar regra do B63 (esconder no entry change-trend) — aqui “pular” = abandonar a mudança, o que o pedido pede explicitamente também no fluxo standalone.
  • Tiles brancos + cor da tendência, não transparentes como B63. Rejeitado: mesma skin do sinal (perderia o mapeamento visual favorável/desfavorável); fill sólido primary.
  • Só opções ≠ status atual. Rejeitado: listar as três sempre (ruído; “salvar” a mesma tendência).
  • Prefill quando origem ≠ standalone vazio. Rejeitado: sempre textarea vazia (pede re-digitação do contexto que o fluxo pai já tem).
  • Salvar explícito (não auto-save B24). Rejeitado: gravar ao escolher o tile (nota obrigatória).
  • i18n: status, entryAction, skipTrendChange, notePrefillSource; copy “Pular mudança de tendência →” / “Limpar” / “Salvar” / “Tendência {label}”.

Questões em aberto

  • Extrair tile compartilhado com B63 agora? Opções: A componente compartilhado WizardChoiceTile com variant neutral | trend | B duplicar leve e extrair no 3º call site. Recomendação: B se B63 ainda não landou; A se B63 já estiver no branch — depth check, não classitis. (assumido)
  • Após Salvar no standalone A3: Início ou “Ir ao município”? Opções: A Início + toast | B pós-commit padrão UX-1 (Fazer outra / Ir ao município / Início). Recomendação: B quando o orquestrador A1/A3 existir; A no tracer deste item. (assumido)

Abordagem proposta

flowchart TB
  Entry["origem: change-trend | embutido A1/A2"] --> Choice["grid tendências ≠ atual"]
  Choice -->|info| Drawer["Drawer detalhes"]
  Choice -->|select| Note["textarea + Limpar + Salvar"]
  Choice & Note -->|Pular| Skip["próximo / Início"]
  Note -->|Salvar| Action["setMunicipalityPoliticalTrend / B24"]

Componentes:

  • WizardTrendChoiceStep + WizardTrendNoteStep em components/campaign/municipality/ (ou shared/ se extrair tile com B63).
  • politicalTrendWizardMeta + buildPoliticalTrendNotePrefill em lib/ — client-safe.
  • Reuso: Drawer, Button, Textarea, B59 trailing slot + contentAlign, labels/politicalTrendBadgeVariant tokens, endpoint/action B24 ✓.
  • Migration: Sem migration (campos já existem).

Dependências

  • Dura: B59. Soft: B60 (município no standalone). Soft: B24 ✓ (write path). Soft: B61 / B63 (prefill de votos/sinal quando embutido). Soft: B45 ✓ (change-trend).

Não escopo

  • Busca de município → B60.
  • Wiring “quer também?” / orquestração A1 completa → fatia posterior UX-1.
  • Trocar o Popover B24 da lista pelo grid de tiles → Adiado.
  • Wizard de liderança (A4) / demanda (A5).

Rabbit holes

  • Unificar visual B63+B64 num design system de “choice tiles” antes do 2º call site. Mitigação: sibling + extrair só com 2 implementações no branch.
  • CMS / Lexical nos textos de Info. Mitigação: constantes em lib/ até R6/assessoria.
  • Recalcular sugestões E11 ao salvar tendência. Mitigação: write path atual; E11 reavalia no próximo load.

Adiado com gatilho

  • Grid de tendência no Popover B24. Revisitar se o select da lista continuar gerando dúvida de classificação em campo.
  • Copy longa dos Drawers revisada pela assessoria. Revisitar no R6.
  • Prefills adicionais (nível E14, troca de assessor). Revisitar quando esses passos embutirem A3.

Referências