mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-22 04:53:09 +00:00
112 lines
11 KiB
Markdown
112 lines
11 KiB
Markdown
# 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
|