mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-17 04:23:07 +00:00
Replace all project-local .cursor/ path references with .agents/ across rules, skills, environment config, hooks, and ignore files. Keep Cursor editor paths (~/.cursor/, window.cursor, CURSOR_API_KEY) and vendored Impeccable editor-hook paths unchanged.
168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# Etapa de ajuste de votos no wizard (cenários + atalhos)
|
||
|
||
Status: **entregue** (2026-07-29)
|
||
Atualizado em: 2026-07-29
|
||
Item do roadmap: [docs/roadmap.md](../roadmap.md) (Trilha B, item B61 — UX-1 wizards)
|
||
Impeccable: C — UI nova de passo numérico com coerência entre cenários
|
||
Appetite: ~1–1,25 dia eng; 3 sub-passos de cenário + atalhos + navegação de violação; grava via action existente no wiring A1 (neste item: UI + validação client espelhando servidor)
|
||
Responsável: —
|
||
|
||
## As-built (entrega)
|
||
|
||
### Contrato de URL e ordem de edição
|
||
|
||
- `?cenario=central|pessimistic|optimistic` em `/campanha/acoes/atualizar-votos?municipio=<slug>`; default `central`; valor inválido → redirect canônico para `central`.
|
||
- Ordem ritual **média → pessimista → otimista** (`WIZARD_VOTE_SCENARIO_EDIT_ORDER` em `src/lib/wizardVoteEstimate.ts`); invariante de armazenamento continua `pessimistic ≤ central ≤ optimistic` via `getVoteEstimateOrderViolation`.
|
||
- Helpers: `applyVoteShortcut`, `getWizardVoteViolation`, `wizardActionHref(slug, municipio?, scenario?)`.
|
||
|
||
### Gravação
|
||
|
||
- **Um POST batch** ao concluir o passo otimista (`POST /campanha/municipios/expected-votes` → `setMunicipalityExpectedVotes`), não três writes por cenário.
|
||
- Sucesso: mensagem + placeholder do próximo passo A1 (B63) + link "Voltar ao Início".
|
||
|
||
### UI
|
||
|
||
- `WizardExpectedVotesStep` substitui `WizardMunicipalitySelectedStub` **somente** em `atualizar-votos` com município escolhido.
|
||
- Um cenário visível; input grande (`text-2xl`/`text-3xl`); atalhos `2×` · `±50` · `±100`; CTA nomeado por cenário.
|
||
- Violação: banner warning + `router.replace` para o cenário quebrado + botão "Voltar para [cenário editado]".
|
||
- `CampaignWizardShell`: caption sticky; `previousHref` = cenário anterior ou busca B60.
|
||
|
||
### Testes
|
||
|
||
- Unit: `tests/unit/wizardVoteEstimate.unit.spec.ts`, `campaignActionRoutes.unit.spec.ts`.
|
||
- E2e: `campaignHomeActions.e2e.spec.ts` — avanço média→pessimista; violação pessimista> média → banner + retorno.
|
||
|
||
### Fora (inalterado)
|
||
|
||
- Preview cobertura E8 no passo; wiring completo A1 (sinal/tendência/resumo B63/B64).
|
||
|
||
### Regressão conhecida (2026-07-30 → ~~B76~~ ✓)
|
||
|
||
~~Jump+warning ao confirmar pessimista `> média` quebrava: `useEffect` limpava `violationEditedScenario` na troca de `?cenario=`.~~ **Corrigido em B76** — preservar estado no jump ao cenário violado; limpar ao editar draft/atalho.
|
||
|
||
### Emenda UX (2026-07-30 → ~~B77~~ ✓)
|
||
|
||
Ritual de três passos `?cenario=` **substituído** por uma tela com os três inputs + strip (como popover da lista); validação inline no confirm. Ver [simplificar-ajuste-votos-wizard.md](simplificar-ajuste-votos-wizard.md).
|
||
|
||
## Design (Impeccable)
|
||
|
||
Âncoras: `PRODUCT.md` (Feel the action; Clarity under pressure) / `DESIGN.md` · `VoteEstimateScenarioInputs` / `MunicipalityListExpectedVotesControl` · tema `campaign`.
|
||
|
||
Na implementação: shape → craft → critique → polish.
|
||
|
||
Brief compacto:
|
||
|
||
- **Persona:** CG no celular ajustando Cairu −100 / Salinas 300→150; quer atalho, não teclado minucioso.
|
||
- **Job principal:** editar **um cenário por vez** (média → pessimista → otimista), com atalhos e confirmação explícita para o próximo.
|
||
- **Estratégia de cor:** Restrained; warning de coerência usa tom de alerta do tema (não Signal Red decorativo).
|
||
- **Edit where you see:** não neste passo — é fluxo com **submit explícito** por cenário (“Ajustar estimativa pessimista →”), exceção já prevista em `campanha-edit-where-you-see` para confirmação.
|
||
- **Anti-goals:** três inputs na mesma tela com um “Salvar”; input enorme estilo hero-metric SaaS; auto-save silencioso sem CTA.
|
||
|
||
## Dados → decisão → apresentação
|
||
|
||
- **Vou apresentar dados?** Sim — valor atual de `expectedVotes[cenário]` e o valor em edição.
|
||
- **Decisões:** staff escolhe o novo número da projeção da mesa por cenário; decide se corrige coerência ou volta ao cenário que quebrou.
|
||
- **Forma:** **número + contexto** (rótulo do cenário + valor atual). **Rejeitado:** chart; três gauges; % estadual.
|
||
- **Profile:** 1 inteiro por passo; ordem `pessimistic ≤ central ≤ optimistic` (`getVoteEstimateOrderViolation`).
|
||
- **Anti-goals de dado:** não misturar `declaredVotes` de liderança; liderança nunca vê esta etapa.
|
||
|
||
## Contexto
|
||
|
||
Ação A1 do Início ([fluxos-acao-primeiro-inicio.md](fluxos-acao-primeiro-inicio.md)): após escolher município (**B60**), ajustar estimativas. Pedido (2026-07-29):
|
||
|
||
- Input **já preenchido** com o valor atual; editável.
|
||
- Atalhos: **2×**, **+50**, **−50**, **+100**, **−100** (aplicam sobre o valor corrente do input).
|
||
- Input **grande, não enorme**.
|
||
- Ordem fixa: **média → pessimista → otimista** (`central` → `pessimistic` → `optimistic`).
|
||
- Se um cenário **quebrar a lógica** com um já definido, navegar **para o cenário que ficou inconsistente**, mostrar **warning** (por quê) e atalho para **voltar ao cenário que a pessoa acabou de editar**.
|
||
- CTA por passo: ex. **“Ajustar estimativa pessimista →”** (não auto-avanço mudo).
|
||
|
||
Invariante de servidor já existe: `getVoteEstimateOrderViolation` + hook em `Municipality` / `VOTE_ESTIMATE_ORDER_ERROR_MESSAGE` (`src/lib/voteEstimate.ts`).
|
||
|
||
## Objetivos
|
||
|
||
- Etapa(s) `WizardExpectedVotesStep` (ou uma rota com `?scenario=`) no **B59**.
|
||
- Estado local dos três números; ao confirmar um cenário, validar contra os já confirmados; se violar, `setScenario(violation)` + banner + link “Voltar para [cenário editado]”.
|
||
- Atalhos mutam o draft (floor 0, ceiling `MAX_VOTE_COUNT`); `2×` = dobrar o valor atual do input (se vazio/0, definir comportamento: ficar 0 ou no-op — **recomendação:** no-op se <1).
|
||
- CTA confirma o cenário e avança (ou conclui o bloco de votos e devolve ao orquestrador A1).
|
||
- Reusar labels `voteEstimateScenarioLabels` (Média / Pessimista / Otimista).
|
||
- Escrita persistente: **reusar** action/endpoint de `expectedVotes` já usados pela lista (`MunicipalityListExpectedVotesControl` / POST expected-votes) — neste item pode entregar UI + schema de passo; o commit final do A1 pode batchar os três no wiring. **Mínimo:** não inventar segunda semântica de ordem.
|
||
- Staff-only; sem migration / Consent.
|
||
- Unit: coerência (casos que forçam jump + atalho de retorno); atalhos aritméticos.
|
||
|
||
## Decisões travadas
|
||
|
||
- **Ordem de edição: média → pessimista → otimista** (pedido). **Rejeitado:** três campos numa tela; ordem pessimista-primeiro (é a ordem do invariante de armazenamento, não do ritual de mesa).
|
||
- **Confirm explícito por cenário** (CTA nomeado). **Rejeitado:** auto-save estilo B27 (pedido pede botão; e coerência cross-cenário pede commit consciente).
|
||
- **Violação → navegar ao cenário quebrado + warning + atalho de retorno.** **Rejeitado:** só toast bloqueando; forçar edição inline sem mudar de passo.
|
||
- **Atalhos sobre o valor do input**, não sobre o valor persistido antigo após dirty. **Rejeitado:** resetar ao “atual” a cada atalho.
|
||
- **i18n:** `central`/`pessimistic`/`optimistic` nos ids; copy “Ajustar estimativa … →”.
|
||
|
||
## Questões em aberto
|
||
|
||
- **Gravar no servidor a cada CTA de cenário ou só no commit final do A1?** **Opções:** A por cenário | B batch no fim. **Recomendação:** B no wiring A1 (um write); este item valida localmente e devolve os três valores — evita half-write se o CG abandonar no pessimista. _(assumido — validar na implementação do A1)_
|
||
|
||
## Abordagem proposta
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Mun["município B60"] --> C["passo Média"]
|
||
C --> P["passo Pessimista"]
|
||
P --> O["passo Otimista"]
|
||
C & P & O --> V{"ordem ok?"}
|
||
V -->|não| Jump["vai ao cenário violado + warning"]
|
||
V -->|sim| Next["próximo bloco / quer também?"]
|
||
```
|
||
|
||
Componentes:
|
||
|
||
- **`WizardExpectedVotesStep`**: input grande (`text-2xl`/`text-3xl` — medir no craft; não `text-6xl`), fila de atalhos (`Button` outline), CTA, banner de coerência.
|
||
- **Helper puro** `applyVoteShortcut(value, 'double' | '+50' | …)` + reuso `getVoteEstimateOrderViolation`.
|
||
- **Migration:** Sem migration (campos já existem).
|
||
|
||
## Dependências
|
||
|
||
- Dura: **B59**. Soft: **B60** (município já escolhido). Reuso: A10 ✓ / `voteEstimate.ts` / controle da lista.
|
||
|
||
## Não escopo
|
||
|
||
- Wiring completo A1 (sinal/tendência/resumo) → fatia posterior UX-1.
|
||
- Edição de `votePledge.estimatedVotes` → fora (esta etapa = `municipality.expectedVotes` da mesa).
|
||
- Leader → lockdown.
|
||
|
||
## Rabbit holes
|
||
|
||
- **Mini-spreadsheet dos 3 cenários com sync bidirecional.** **Mitigação:** um cenário visível por vez.
|
||
- **Recalcular meta E8 / cobertura ao vivo no passo.** **Mitigação:** número cru; cobertura fica no resumo A1 ou no Quadro.
|
||
|
||
## Adiado com gatilho
|
||
|
||
- **Preview de cobertura E8 no rodapé do passo.** Revisitar se o CG pedir “isso fecha a meta?” durante o ajuste (sessão).
|
||
|
||
## Já resolvido no simplify (não reabrir)
|
||
|
||
- Ramo morto em `buildWizardVoteViolationMessage` (cenário `central` com `optimistic < central` — `getVoteEstimateOrderViolation` já devolve `'optimistic'`).
|
||
- Estado duplicado de mensagem de violação (`violationReturn` → só `violationEditedScenario` + `activeViolation.message`).
|
||
- Banner de violação obsoleto ao voltar de cenário (limpa `violationEditedScenario` na troca).
|
||
- `parseWizardVoteDraft` removido (B77+); parsing fica só em `VoteEstimateScenarioInputs.parseScenarioInput`.
|
||
- Alias `WizardVoteEditScenario` = `VoteEstimateScenario`; `getWizardVoteViolation` lazy.
|
||
- Constante `MUNICIPALITY_EXPECTED_VOTES_ENDPOINT` compartilhada com `MunicipalityListExpectedVotesControl`.
|
||
- **B77+:** `getWizardVoteViolation` devolve `highlightScenarios` num único pass; `MUNICIPALITY_EXPECTED_VOTES_SAVE_ERROR_MESSAGE` compartilhada wizard+lista; prop `municipalitySlug` morta no passo; `hasWizardScenarioParam` delega a `parseWizardMunicipioParam`; CTA `WIZARD_VOTES_FINAL_CTA_LABEL` em `campaignWizardCopy.ts`.
|
||
|
||
## Explicitamente fora (pós-/simplify, defer)
|
||
|
||
| Achado | Gatilho para revisitar |
|
||
| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||
| Unificar `VoteEstimateScenarioInputs.parseScenarioInput` com clamp `MAX_VOTE_COUNT` no wizard | 3ª superfície de input de votos **ou** passe repo-wide de parsing numérico pt-BR |
|
||
| Extrair shell `ExpectedVotesEditor` (wizard + lista) | `/simplify` medir duplicação >~60 linhas **e** políticas de save alinhadas (hoje wizard = confirm, lista = autosave) |
|
||
| Validar ordem pessimista/média/otimista no client na lista (popover) | Produto pedir feedback inline antes do autosave **ou** 3º editor inline de votos estimados |
|
||
| `useCampaignCellAutosave` no wizard | **Não** — submit explícito é decisão de produto (`campanha-edit-where-you-see`); ver Não escopo B77 |
|
||
| Validar body do wizard com `voteEstimateScenarioFieldsSchema` no client | Gravação por cenário (write parcial) em vez do batch único |
|
||
| Helper genérico `readCampaignJsonMutationResult` | 3ª rota/painel wizard com o mesmo shape de resposta JSON |
|
||
| Generalizar `parseWizardMunicipioParam` / `resolveWizardScenarioParam` num parser de query do wizard | B63/B64 reutilizarem `?cenario=` ou outro param de passo na mesma rota |
|
||
|
||
## Referências
|
||
|
||
- [fluxos-acao-primeiro-inicio.md](fluxos-acao-primeiro-inicio.md) · [cenarios-estimativa-votos.md](cenarios-estimativa-votos.md) · `src/lib/voteEstimate.ts` · `MunicipalityListExpectedVotesControl.tsx` · `VoteEstimateScenarioInputs.tsx` · collection `Municipality` hook de ordem
|
||
- AGENTS.md — assimetria leader; `overrideAccess: false`
|
||
- `PRODUCT.md` / `DESIGN.md` · `.agents/rules/campanha-edit-where-you-see.mdc` (exceção submit explícito)
|