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

11 KiB
Raw Permalink Blame History

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)

[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