teqo-backup/docs/plans/cards-time-de-voce-escala-cabeca.md

112 lines
11 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.

# Card "Time de você": cabeça do visitante proporcional à dos candidatos
Status: rascunho
Atualizado em: 2026-09-19
Issue: #1197
Priority: P2
Impeccable: C — ajuste de comportamento visual num funil público existente (sem controle novo)
Design UI: docs/plans/cards-time-de-voce-escala-cabeca-ui-design.html
Appetite: ~1–1,5 dia eng; cabeça do visitante em proporção com os candidatos, com fallback seguro
Responsável: —
## Intenção
O card "Time de você" (S15, #1161) já enquadra a foto do visitante sozinho — mas só garante que o recorte cubra a janela da foto, ancorado no topo. Na prática, quem manda uma selfie de longe fica com a cabeça minúscula ao lado dos candidatos; quem manda um enquadramento fechado fica gigante. O pedido que abriu este item foi direto:
> "É possivel automaticamente medir o melhor tamanho para colocar a foto? Talvez basear no tamanho da cabeça do usuario e dos candidatos para ficar proporcional?"
A resposta é sim: medir a cabeça dos dois lados com a mesma régua (detecção de rosto) e usar essa proporção para escolher o zoom do enquadramento automático — com os limites do card mandando acima de tudo e, quando não der para medir, valendo exatamente o enquadramento de hoje. É um ajuste de comportamento no funil público, sem controle novo e sem nada saindo do aparelho.
## Persona e fluxo
- **Persona / contexto:** militante no celular, escolheu uma selfie razoável e viu na prévia a cabeça grande demais (foto de perto) ou pequena demais (foto de longe) em relação aos candidatos.
- **Job principal:** a foto entrar na proporção certa sozinha, sem ajustar nada — e, se a medida não for possível, continuar exatamente como hoje.
- **Fluxo desejado:** escolhe a foto → acompanha o recorte no aparelho → o card mede a cabeça do visitante e compara com a dos candidatos → ajusta o enquadramento para ficarem na mesma ordem de grandeza (±20%) → confere a prévia (arrastar/zoom como escape) → baixa o PNG. Sem rosto detectado ou detecção indisponível, a prévia sai como sai hoje, sem aviso de erro.
- **Anti-goals de produto:** editor de enquadramento obrigatório; detecção de rosto como requisito do fluxo; segundo motor/pesquisa de rosto a cada ajuste; prometer recorte/medida perfeitos; expor erro de detecção; alterar o segmentador ou os 3 modelos existentes; upload/serviço/rede.
### Esboço de fluxo (C)
```text
[foto escolhida] → [recorte no aparelho: progresso | erro + retry]
→ [rosto medido?] ─ sim → [zoom para a cabeça ficar ±20% da cabeça dos candidatos]
└ não → [enquadramento de hoje, pelo contorno]
→ [prévia (arrastar/zoom como escape)] → [card pronto] → [baixar PNG]
```
### Design UI (C)
- Design UI (gate): `docs/plans/cards-time-de-voce-escala-cabeca-ui-design.html`
- Cenas: prévia "antes" (cabeça pequena demais / grande demais) contra "depois" proporcional e o caminho de fallback (idêntico ao de hoje), em mobile e desktop; sem controle novo.
- `Design tier: DEGRADED` — o frontier `openai/gpt-5.6-sol` bateu quota; o artefato saiu do `designer-degraded` e **não certifica**: exige sign-off humano no gate/PR.
## Objetivo e aceite
- A cabeça do visitante no card fica na mesma ordem de grandeza das cabeças dos candidatos da arte oficial, com tolerância de ±20%, medida pela mesma régua nos dois lados.
- O enquadramento automático continua sendo o padrão: nenhum passo novo, nenhum botão novo; arrastar/zoom seguem como escape.
- O rosto do visitante nunca é cortado pelo enquadramento proporcional.
- A cobertura da janela da foto prevalece: nunca sobra buraco no card, mesmo que isso limite a proporção.
- Fallback obrigatório e silencioso: sem rosto detectado, com detecção indisponível ou em qualquer falha, vale o enquadramento atual pelo contorno — o card nunca falha nem mostra erro por causa da detecção de rosto (o único erro recuperável continua sendo o do recorte de fundo).
- Tudo no aparelho; nenhum byte da foto sai; a nota de privacidade existente continua visível e verdadeira.
- O resto do funil fica intocado: os 3 modelos anteriores, a galeria, os textos e os controles seguem como estão.
## Dados (intenção)
- **Vou apresentar dados?** Não.
- **Decisões desbloqueadas:** N/A — nenhuma métrica é apresentada; a medida de cabeça é geometria efêmera no aparelho, não um dado de produto.
- **Forma:** _adiada ao plano de implementação_ — aqui só a restrição de produto: nada de nome, foto ou medida saindo do aparelho nem entrando em analytics.
## Dados da decisão (literais)
- ID `S18`; slug `cards-time-de-voce-escala-cabeca` (arquivo `docs/plans/cards-time-de-voce-escala-cabeca.md`); tipo `feature`; Priority `P2`; Impeccable `C — ajuste de comportamento visual num funil público existente (sem controle novo)`; Design UI: `docs/plans/cards-time-de-voce-escala-cabeca-ui-design.html`.
- O enquadramento automático passa a mirar a proporção da cabeça: a cabeça do visitante deve ficar na mesma ordem de grandeza das cabeças dos candidatos da arte oficial, tolerância ±20%.
- Métrica única dos dois lados: o tamanho da cabeça é medido pela detecção de rosto (mesma métrica sobre a arte dos candidatos e sobre a foto do visitante); a referência dos candidatos é medida uma vez sobre a arte-mestre e registrada como constante literal no código.
- Em foto com mais de um rosto, vale o maior rosto (o do visitante).
- Fallback obrigatório: sem rosto detectado, com detecção indisponível ou em qualquer falha, o enquadramento atual pelo bbox continua valendo — o card NUNCA falha nem mostra erro por causa da detecção de rosto (só o recorte de fundo tem estado de erro).
- A cobertura da janela da foto prevalece: se a proporção exigir ampliar além do necessário para cobrir, a cobertura manda (nunca sobra buraco no card).
- Nenhum controle novo: continua automático, com arrastar/zoom como escape (como hoje).
- O rosto nunca é cortado pelo enquadramento proporcional.
- 100% no aparelho; o modelo de detecção segue o padrão do segmentador (mesma origem, commitado, licença documentada, lazy: só o modelo time paga); sem pin de modelo de execução (roda no modelo padrão da sessão; provider `openai` é reservado ao design).
- A janela da foto do card time continua a do S15: x=286, y=439, largura=592, altura=577 (card 1080×1440).
## Direção no codebase (hipótese)
- **Áreas prováveis:** detecção no adapter `src/components/cards/cardCutout.ts` reaproveitando `@mediapipe/tasks-vision` + modelo de rosto commitado em `public/cards/`; matemática pura nova/estendida em `src/lib/cardPhotoTransform.ts` (a partir de `frameCardPhotoOnBbox`); estado no `useCardCutout.ts`; render/prévia no `src/components/cards/CardComposer.tsx`.
- **Precedente a olhar:** S15 (`docs/plans/cards-time-de-voce-impl.md`) — motor/wasm/modelo/licença em `public/cards/` e o seam do stub; testes `tests/unit/cardPhotoTransform.unit.spec.ts`, `cardRender.unit.spec.ts` e e2e `tests/e2e/frontend.e2e.spec.ts` (stub do motor via `NEXT_PUBLIC_CARDS_CUTOUT_STUB=1`).
- **Risco de acoplamento:** a detecção pega carona no mesmo caminho do recorte (o stub de e2e cobre hoje só o segmentador e o e2e falha em qualquer console error); pan/zoom do visitante continuam sendo o escape e nada pode travar a prévia.
## Dependências
- S15 (#1161) entregue — o modelo, o recorte e o auto-enquadramento existem.
- S17 não é dependência, mas os dois tocam o mesmo pipeline — se rodarem em paralelo, serializar.
## Fora de escopo
- Editor de enquadramento obrigatório; qualquer controle novo de proporção.
- Detecção de rosto como requisito do fluxo (foto sem rosto segue funcionando como hoje).
- Identificação de pessoa / reconhecimento facial (detecção ≠ identificação), escolha entre vários rostos, rosto "perfeito".
- Re-detectar o rosto a cada arrastar/zoom (a medida é feita no momento do recorte).
- Alterar o segmentador, os 3 modelos antigos, a arte-mestre, os textos do funil ou a privacidade.
- Upload/serviço/rede; métricas de uso da detecção; modelos adicionais/CMS/compartilhamento (cortados no S15, seguem cortados).
## Rabbit holes de produto
- **Proporção virar editor de enquadramento.** Se alguém "só completar": nasce um passo obrigatório de ajuste fino de cabeça. **Corte neste item:** automático, ±20% quando der; arrastar/zoom como escape de sempre.
- **Detecção virar requisito.** Se alguém "só completar": foto sem rosto detectado vira erro ou bloqueia o card. **Corte neste item:** fallback silencioso ao enquadramento atual; o único erro recuperável continua sendo o do recorte.
- **Medir "no olho".** Se alguém "só completar": a régua vira opinião e cada ajuste reabre a conta. **Corte neste item:** métrica única (caixa do rosto), mesma dos dois lados, referência literal registrada.
- **Cabeça proporcional a qualquer custo.** Se alguém "só completar": zoom sem limite, buraco no card ou rosto cortado. **Corte neste item:** cobertura > proporção > nada; rosto nunca cortado; fallback.
## Questões em aberto (produto)
- **Medir a referência dos candidatos na arte em tempo de execução ou como constante medida uma vez?** **Opções:** A) constante literal medida uma vez sobre a arte-mestre | B) medir a arte a cada sessão | C) híbrido. **Recomendação:** A — a arte-mestre é fixa e já versionada; a constante é auditável, não custa nada no aparelho e não depende de a detecção acertar a arte a cada uso. _(assumido — validar com produto)_
- **Prover também um toggle para desligar a proporção ou deixar só automático?** **Opções:** A) só automático com fallback | B) toggle do visitante | C) flag interna. **Recomendação:** A — anti-goal "controle novo"; se o ajuste incomodar, arrastar/zoom já é o escape. _(assumido — validar com produto)_
- **Qual detector usar?** **Opções:** A) `FaceDetector` (caixa do rosto) | B) `FaceLandmarker` (malha facial) | C) motor próprio. **Recomendação:** A — a medida decidida é o tamanho da cabeça, e a caixa do rosto já a entrega; menos peso no celular e menos superfície. _(assumido — validar com produto)_
## Referências
- GitHub Issue #1197
- Design UI (gate): `docs/plans/cards-time-de-voce-escala-cabeca-ui-design.html` (+ assets em `cards-time-de-voce-escala-cabeca-ui-design-assets/`)
- `docs/plans/cards-time-de-voce.md` e `cards-time-de-voce-impl.md` (S15, #1161)
- `src/lib/cardPhotoTransform.ts` (`frameCardPhotoOnBbox`), `src/components/cards/cardCutout.ts`, `useCardCutout.ts`, `CardComposer.tsx`
- `public/cards/team-card-base.png` / `team-card-example.jpg` (referência visual) e `selfie_segmenter.LICENSE.txt` (padrão de licença)
- `tests/unit/cardPhotoTransform.unit.spec.ts`, `tests/unit/cardRender.unit.spec.ts`, `tests/e2e/frontend.e2e.spec.ts`
- `AGENTS.md` — reserva do provider `openai` ao design e convenções do funil de cards