mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-18 14:13:06 +00:00
113 lines
8.9 KiB
Markdown
113 lines
8.9 KiB
Markdown
# C226 — Central de Conteúdos: frame estático para vídeos com arquivo
|
||
|
||
Status: rascunho
|
||
Atualizado em: 2026-09-25
|
||
Issue: #1352
|
||
Priority: P2
|
||
Impeccable: B — encaixe no slot de mídia já existente do card público, sem rota ou tela nova
|
||
Design UI: docs/plans/central-conteudos-preview-frame-video-ui-design.html
|
||
Appetite: ~1–2 dias eng; um outcome verificável — reconhecer um vídeo com arquivo antes de reproduzi-lo
|
||
Responsável: —
|
||
|
||
## Intenção
|
||
|
||
Na Central pública, o carregamento do vídeo só acontece depois do play. Isso é bom para quem está numa conexão lenta, mas deixa o card sem uma pista visual quando a pessoa ainda está escolhendo o que vale assistir.
|
||
|
||
Este item quer uma imagem leve e estática para cada peça de vídeo que já tem arquivo no acervo da Central. A pessoa deve reconhecer a peça antes de apertar play, sem buscar o arquivo de vídeo antecipadamente.
|
||
|
||
## Persona e fluxo
|
||
|
||
- **Persona / contexto:** visitante da campanha no celular ou desktop, folheando peças para escolher material para assistir e compartilhar.
|
||
- **Job principal:** distinguir vídeos pelo que aparece na tela e decidir qual deles quer reproduzir, sem abrir vários players.
|
||
- **Fluxo desejado:** abre `/conteudos` → vê o frame estático, o botão de play e os metadados → toca em play quando escolher → o vídeo carrega naquele momento.
|
||
- **Anti-goals de produto:** não transformar a Central em galeria pesada, não carregar todos os vídeos, não criar player ou tela de edição, não baixar mídia de terceiro e não misturar esta fatia com o acervo de falas.
|
||
|
||
### Esboço de fluxo (B)
|
||
|
||
```text
|
||
[/conteudos]
|
||
→ card de vídeo com arquivo
|
||
→ frame estático + play + título/metadados
|
||
→ a pessoa reconhece a peça e decide
|
||
→ toca no play
|
||
→ somente esse vídeo é buscado e reproduzido
|
||
→ sem frame disponível: slot neutro + play honesto
|
||
```
|
||
|
||
### Design UI (B)
|
||
|
||
- Design UI (gate): `docs/plans/central-conteudos-preview-frame-video-ui-design.html` — cenas desktop e mobile do card antes do play, fallback neutro e contraste entre frame e player durante a reprodução.
|
||
|
||
## Objetivo e aceite
|
||
|
||
- Toda peça de vídeo publicada e com arquivo no acervo exibe pelo menos um frame estático no catálogo público antes do play.
|
||
- O frame é uma pista visual leve: não promete representar um momento específico, não substitui o arquivo e não altera a reprodução.
|
||
- A peça não busca o arquivo de vídeo antes do play. O frame pode ser carregado como imagem, mas não deve puxar o vídeo nem o áudio.
|
||
- Se o frame não puder ser produzido, o card mantém um estado neutro com play e não mostra imagem quebrada nem tenta repetir a busca sem limite.
|
||
- Peça-link de YouTube ou Instagram, áudio, foto, texto e card mantêm o comportamento atual; esta entrega não promete frame local para uma peça que não tem arquivo.
|
||
- O kill switch continua valendo: uma peça despublicada não expõe sua mídia privada pelo novo preview.
|
||
- A lista interna `/campanha/comunicacao/conteudos` não ganha player nem uma segunda visualização de frame; a lista pública é o alvo obrigatório.
|
||
|
||
## Dados (intenção)
|
||
|
||
- **Vou apresentar dados?** Não — não há número, série, ranking ou métrica. O frame serve para reconhecimento visual.
|
||
- **Decisões desbloqueadas:** a pessoa escolhe qual vídeo reproduzir pela imagem; a equipe de conteúdo não precisa abrir cada peça para descobrir a cena.
|
||
- **Forma:** _adiada ao plano de implementação_ — nenhuma tabela, gráfico ou contador; a restrição é uma imagem leve e estática.
|
||
|
||
## Dados da decisão (literais)
|
||
|
||
- Identificador: `C226`.
|
||
- Rota pública: `/conteudos`.
|
||
- Regra visual: **pelo menos um frame estático por peça de vídeo com arquivo**.
|
||
- Regra de carregamento: **nenhum request do arquivo de vídeo antes do play**.
|
||
- Regra de falha: **fallback neutro sem imagem quebrada**.
|
||
- Peças com `sourceUrl` e sem arquivo local continuam peça-link; thumbnail remoto de plataforma não conta como frame do arquivo nesta fatia.
|
||
- O frame é uma pista de reconhecimento, não uma escolha editorial obrigatória nem um novo arquivo para baixar.
|
||
|
||
## Direção no codebase (hipótese)
|
||
|
||
- **Áreas prováveis:** `src/components/conteudos/ContentPieceMedia.tsx` e `ContentPieceCard.tsx` para o slot de mídia; `src/lib/contentPieceCatalog.ts` e `src/utilities/content/contentPieceReads.ts` para a projeção pública; `src/collections/ContentMedia.ts`, `src/collections/ContentPiece.ts` e o processamento de `src/utilities/content/contentPieceJob.ts` para a origem do arquivo. A forma de gerar, guardar e invalidar o frame fica para o plano de implementação.
|
||
- **Precedente a olhar:** o contrato lazy do S27 em `docs/plans/central-conteudos-publica.md:44-66`; a separação entre arquivo e peça-link em `docs/plans/central-conteudos-ingestao.md:42-51` e `central-conteudos-link-instagram.md:47-60`; a política de mídia privada já documentada em `ContentMedia.ts`.
|
||
- **Risco de acoplamento:** `ContentPieceMedia` também é usado em outras superfícies públicas. O executor deve preservar o play sob demanda, o kill switch e a separação entre arquivo privado e peça-link; não deve reusar nem alterar o preview do acervo de falas C182.
|
||
|
||
## Dependências
|
||
|
||
- C211 — pipeline e acervo de peças com arquivo.
|
||
- S27 — catálogo público, filtro e contrato de reprodução sob demanda.
|
||
- C193/C199 e C220 — soft: preservam a política de mídia privada e a distinção entre arquivo oficial e link.
|
||
|
||
## Fora de escopo
|
||
|
||
- Preview do acervo de falas em `/campanha/comunicacao/acervo` e o frame do C182.
|
||
- Player, autoplay, hover-play, preview em movimento, editor de timestamp, seleção editorial ou recorte de vídeo.
|
||
- Download, persistência ou thumbnail de mídia de terceiros; peça-link continua circulando pelo link.
|
||
- Backfill/reprocessamento em massa, nova tela de ingestão, nova analytics, Consent ou alteração do kill switch.
|
||
- Mudança na lista interna de comunicação, no estúdio de cards ou no shell da Central.
|
||
|
||
## Rabbit holes de produto
|
||
|
||
- **Gerar frame para tudo.** Se alguém “só completar”, o item vira fila, backfill, armazenamento e reconciliação de todos os vídeos. **Corte neste item:** peças de vídeo com arquivo no acervo; a forma de geração fica no impl-plan.
|
||
- **Usar thumbnail de plataforma como se fosse frame local.** Isso mistura uma origem externa com um arquivo oficial e promete uma imagem que não pertence à peça. **Corte:** peça-link não recebe frame local nesta fatia.
|
||
- **Fazer o vídeo carregar junto da imagem para ficar mais rápido.** Isso desfaz o ganho do carregamento sob demanda. **Corte:** imagem antes, arquivo apenas depois do play.
|
||
- **Abrir um editor de frame.** Escolher timestamp, cortar imagem e revisar tudo vira trabalho de produção. **Corte:** um frame automático ou o fallback neutro.
|
||
|
||
## Questões em aberto (produto)
|
||
|
||
- **Qual frame usar quando o vídeo é elegível?** **Opções:** A) primeiro frame decodificável | B) frame representativo escolhido por uma regra determinística, como uma fração da duração | C) seleção manual pela assessoria. **Recomendação:** A — atende ao pedido com uma decisão simples e evita fingir que existe um momento editorial escolhido. _(assumido — validar no gate)_
|
||
- **O que fazer quando a extração falhar?** **Opções:** A) fallback neutro com play | B) thumbnail de uma plataforma externa | C) esconder o card. **Recomendação:** A — o card continua honesto e não inventa uma origem. _(assumido — validar no gate)_
|
||
- **O preview precisa aparecer também na página individual?** **Opções:** A) tornar obrigatório também na página da peça | B) validar apenas o catálogo nesta fatia. **Recomendação:** B — o relato é sobre o catálogo; qualquer efeito em uma superfície compartilhada será avaliado sem criar um segundo outcome. _(assumido — validar no gate)_
|
||
|
||
## Referências
|
||
|
||
- `docs/plans/central-conteudos-publica.md:40-80` — S27, rota, slot de mídia e play sob demanda.
|
||
- `docs/plans/central-conteudos-ingestao.md:42-76` — C211, arquivo versus peça-link e processamento.
|
||
- `docs/plans/central-conteudos-link-instagram.md:40-67` — C220, mídia oficial e limites de terceiro.
|
||
- `src/components/conteudos/ContentPieceMedia.tsx:147-196` — estado atual de vídeo antes do play.
|
||
- `src/components/conteudos/ContentPieceCard.tsx:132-144` — slot de mídia do card público.
|
||
- `src/lib/contentPieceCatalog.ts:655-739` — projeção pública do arquivo e distinção `isLink`.
|
||
- `src/collections/ContentMedia.ts:1-45` — dono atual do arquivo privado.
|
||
- `AGENTS.md` e `AGENTS-public.md` — convenções de mídia, UI pública e limites de produto.
|
||
|
||
## Self-score (shaping)
|
||
|
||
**5/5** — (1) a fatia tem um outcome verificável: frame antes do play para vídeo com arquivo; (2) o apetite declarado comporta a geração, a projeção e o fallback sem abrir uma fila editorial; (3) persona, job e aceite estão em linguagem de produto; (4) a direção no codebase é hipótese; (5) não há assinatura, migration, schema ou estratégia de armazenamento decidida no plano.
|