teqo-backup/docs/plans/escala-dry-pos-s30.md

73 lines
8.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Escala/DRY pós-S30 — fatiar o CardComposer + resíduo do script de assets
Status: rascunho
Atualizado em: 2026-09-23
Issue: #1271 (débito do S30; a Issue própria nasce `depends: [1271]`)
Priority: P3
Impeccable: A — refactor interno do estúdio de cards, sem mudança visual (o e2e da superfície é a prova)
Appetite: ~0,5–1 dia eng (fill-in; três fases pequenas, sem migration)
Responsável: —
## Contexto
A entrega S30 ([cards-estadual-dobradinha-impl.md](cards-estadual-dobradinha-impl.md), Issue #1271) acrescentou o 5º modelo do estúdio de cards. O gatilho do S15 para fatiar o `CardComposer` ("um 5º modelo OU folga de ~0,5 dia no próximo item do funil", [cards-time-de-voce-impl.md](cards-time-de-voce-impl.md) § Adiados) disparou; a Decisão 7 do S30 adjudicou manter o composer único no PR e registrar a dívida aqui — o arquivo saiu de ~830 para ~1100 linhas, com os ramos `processing`/`error`/`ready` inline e ternários aninhados de 3–4 níveis (`canAdvance`/`adjustable`/`eyebrow`/`title`). A passagem `/simplify` (2 revisores) aplicou ~20 correções na própria sessão (R1–R8 abaixo); o que sobrou são débitos maiores que o cleanup e do mesmo lote (mesma superfície: estúdio de cards + script de assets do S30). Sem este item: (a) cada modelo novo (o S31 já está na fila) paga o custo de mexer num arquivo de 1100 linhas com derivações sem teste; (b) o `build-state-deputy-card-assets.mjs` segue com dois passes e predicados gêmeos que podem divergir.
**Coordenação:** o S31 (#1272, colinha) também toca `CardComposer.tsx`/`StateDeputySelect.tsx`; executar este lote **depois** do S31 evita rebase (a Issue depende só de #1271, que destrava sozinho).
## Objetivos
- Os blocos de estado do composer (`processing`/`error`/`ready`, campo de nome, avisos de privacidade) vivem em componentes presentacionais com props tipadas; o `CardComposer` fica com a orquestração (estado, efeitos, canvas).
- `canAdvance`/`adjustable`/`eyebrow`/`title`/estágios de prévia viram funções nomeadas e testáveis (fim dos ternários aninhados por `kind`/estado/seleção).
- `scripts/build-state-deputy-card-assets.mjs` faz um passe único: um `Map` slug→par montado na validação, sem o 2º `readdir` nem o `pick`/`findOne` gêmeos.
- Guardrails: sem migration; nenhuma mudança de DOM/a11y/copy/URL; os 4 modelos antigos intocados; `pnpm gate:fast` + e2e `Cards personalizados` (S14/S15/S30) verdes.
## Fases
1. **F1 (S3, maior ROI) — subcomponentes de estado.** Mover os blocos `step === 'compose' && teamProcessing|teamError|teamReady` (e o campo de nome/avisos que os acompanha) para `src/components/cards/CardComposerStates.tsx`, com props explícitas e sem estado próprio, preservando literais, roles e labels. Opções: A) componentes no mesmo diretório com props explícitas | B) manter inline no arquivo | C) render-props. Recomendação: A — é o dono natural do que hoje é JSX condicional sem dono; rejeitadas B (não reduz o arquivo) e C (cerimônia sem 2º consumidor). Prova: e2e S30/S15 + unit existentes verdes, sem snapshot/DOM novo; `pnpm gate:fast`.
2. **F2 (S3) — derivações puras.** Extrair `canAdvance`, `adjustable`, `eyebrow`, `title` e os estágios de prévia para funções nomeadas (ex. `src/components/cards/cardComposerState.ts`) com unit `// @vitest-environment node` cobrindo a matriz `kind` (name/photo/team/state-deputy) × estado do recorte × seleção × erro de nome. O composer só consome o resultado. Prova: unit novo verde + e2e da superfície.
3. **F3 (S2, carona) — passe único do script de assets.** Montar `Map<slug, { dir, photos, base }>` no 1º passe (validação) e derivar do Map no 2º, eliminando o `readdir` repetido e o par `pick`/`findOne`. Prova: re-executar `pnpm build:state-deputy-card-assets -- --from '<origem>'` deixa `git status public/cards/estaduais` limpo (byte-idêntico).
## Já resolvido no simplify (não reabrir)
- **R1** `renderTeamCard` num ramo só com `subject` discriminado (fim da duplicação de ramo).
- **R2** trava de scroll programático nos dots da galeria (`PROGRAMMATIC_SCROLL_LOCK_MS`).
- **R3** opções do listbox com `tabIndex={-1}` (fim dos 53 tab stops).
- **R4** alvo dos dots 6px→24px (WCAG 2.5.8) + ordem dica→dots do design.
- **R5** picker: scroll da opção ativa ao digitar, mensagem vazia fora do listbox, autofocus só em abertura do usuário, clamp do `activeIndex`, retry ao reescolher o mesmo estadual após falha.
- **R6** `deputyPairReady` exige o par carregado; fallback morto de `photoWindow`; casts do `querySelectorAll`; `.map((file) => file)` morto no script.
- **R7** e2e: comentário dos pixels mágicos, clique nos dots via `aria-current`, nome longo do modelo novo, estado vazio da busca.
- **R8** divergências do designer (destaque do tile novo + escala da prévia S30) portadas e certificadas.
## Explicitamente fora (descartes e defers com gatilho)
- **P2 — 3ª cópia do padrão listbox inline** (`StateDeputySelect` vs `CampaignListOmnibox` vs `RelationChipCell`): **defer**, gatilho já documentado no próprio componente — 4º consumidor com implementação própria (reuso de `StateDeputySelect` não conta) ou um fix de a11y que precise valer nos três.
- **P4 — `nome · número` em 2 lugares**: **descartar** — não é o mesmo formato (legenda `nome · número`; trigger `número · Trocar` + nome em span) e são 2 call sites < 3.
- **P6 + P10 — par JULIO default morto/duplicado** (`cardModels.ts` × `stateDeputyCatalog.ts`; o composer nunca carrega os defaults e `previewSrc` cobre tile/pré-escolha): **defer**, gatilho — o S31 (#1272) acrescenta o 6º modelo e revisita o contrato `CardModel`, ou surge um 2º consumidor do par default.
- **P5 — `window` como nome de parâmetro em `cardRender.ts`**: **descartar** — pureza herdada do S15, sem bug; rename amplo (score 1) por score ≤2.
- **P7 — comentários/mensagens pt-BR no script novo**: **descartar** — família `build:*` mista (`build-radio-artes.mjs` é pt-BR) e comentário não é identificador.
- **P8 — `identitySha256` redundante após o `toEqual`**: **descartar** — precedente idêntico no `municipalityCatalog`; o hash é o guard de regeneração do fixture.
- **P9 — `!` em `tests/unit/cardRender.unit.spec.ts`**: **descartar** — convenção do próprio arquivo (test-only, pré-existente).
## Absorvidos do S34 (2026-09-24)
Débitos que o /simplify do S34 ([cards-colinha-arte-exata-impl.md](cards-colinha-arte-exata-impl.md)) mandou para este lote (mesma superfície):
- **S34-D1 — `name.toLocaleUpperCase('pt-BR')` duplicado** entre a `Linha conferida` do `CardComposer` e o nome desenhado em `renderColinhaCard`: a derivação do texto do nome entra em **F2** (função pura no dono `cardColinha.ts`), consumida pelos dois.
- **S34-D2 — `ensureCardFont(fontFamily)` gateia o fluxo da colinha** (que desenha com o stack Arial, não com a display do site): o efeito de carga é reestruturado em **F1/F2**; hoje uma falha da fonte display derruba um fluxo que não a usa (pré-existente do S31).
## Rabbit holes / Não escopo
- Extrair o listbox compartilhado agora (P2) — três superfícies divergentes (admin/omnibox, chips de relação, estúdio público) e gatilho documentado; abstração prematura.
- Mexer no contrato `CardModel`/defaults (P6) — o S31 já vai tocá-lo.
- Redesenho de prévia/segunda gramática visual, re-harmonização na troca de estadual (assumida no S30), 53 modelos/URL, CMS.
- Mudar copy/literais ou o fluxo dos 4 modelos antigos.
## Self-score (decision-quality)
1. Decisões caras com rejeitadas? **Sim** — F1/F2 com opções e rejeitadas; nada de access/LGPD/schema/unicidade entra (piso 4–5 não se aplica) e descartes/defers estão nomeados com gatilho.
2. Cabe no appetite? **Sim** (~0,5–1 dia, três fases pequenas, sem migration).
3. Rabbit holes nomeados? **Sim** — listbox compartilhado, contrato `CardModel`, re-harmonização.
4. Depth check? **Sim** — reusa composer/script existentes; F2 nasce com unit real, sem módulo de pureza especulativo.
5. Outcome do S30 intocado? **Sim** — comportamento/DOM/copy/URL idênticos; o e2e da superfície é a prova.
**Score: 5/5.**