mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-21 11:43:11 +00:00
85 lines
9 KiB
Markdown
85 lines
9 KiB
Markdown
# Acervo: o player sempre deixa voltar ao YouTube e espera a Câmara gerar o trecho
|
||
|
||
Status: rascunho
|
||
Atualizado em: 2026-09-16
|
||
Issue: #1103
|
||
Priority: P2
|
||
Impeccable: A — N/A sem nova superfície (acréscimo de um controle simétrico no bloco de saída já desenhado + correção de comportamento do resolver)
|
||
Design UI: N/A — sem UI nova
|
||
Appetite: ~0,5–1 dia eng; um outcome verificável: numa fala, quem troca para a Câmara sempre consegue voltar ao YouTube na própria página, e a Câmara gerando o trecho não vira um "falhou" de primeira.
|
||
Responsável: —
|
||
|
||
## Intenção
|
||
|
||
O aviso do dono é um defeito de duas cabeças na mesma fala. Primeira: ao clicar em "Assistir na Câmara", o player troca a superfície para o trecho da Câmara — mas **não existe caminho de volta** para o embed do YouTube na própria página; a única saída passa a ser um link externo, e quem preferia o YouTube fica ilhado. Segunda: quando a Câmara responde "GERANDO", o player trata isso como fracasso na primeira resposta e manda o usuário tentar de novo, quando na verdade a Câmara está apenas transcodificando o trecho e ele fica pronto segundos depois — o retry então "funciona", o que confirma que a espera é curta e o problema é o app desistir cedo. Para a assessoria, no meio da montagem de uma peça, isso custa a fala: ou ela perde a fonte que estava usando, ou acha que o arquivo não existe. A correção é pequena e simétrica — dar o mesmo controle nos dois sentidos e deixar o clique do player esperar um orçamento curto antes de anunciar "gerando/falhou".
|
||
|
||
## Persona e fluxo
|
||
|
||
- **Persona / contexto:** assessoria de comunicação (`communicator`, coordenação e candidatura) em `/campanha/comunicacao/acervo/[id]`, na mesa ou no celular, com prazo curto.
|
||
- **Job principal:** alternar entre a superfície da Câmara e a do YouTube na mesma página, e assistir ao trecho sem ser mandado "tentar de novo" por algo que só estava sendo gerado.
|
||
- **Fluxo desejado:** abre a fala → assiste na superfície preferida (C178) → clica em "Assistir no YouTube" e volta ao embed no ponto da fala → se pedir o trecho da Câmara e ele ainda estiver sendo gerado, o clique espera alguns segundos e o vídeo toca sozinho; se o orçamento estourar, aí sim vê o estado honesto com "Tentar novamente".
|
||
- **Anti-goals de produto:** autenticar no YouTube ou trocar por embed novo; inventar estado ("sucesso" sem verificação de mídia); novo player/editor; baixar/espelhar/transcodificar; novo `Consent`/collection/migration; expor o acervo fora de `/campanha`.
|
||
|
||
## Objetivo e aceite
|
||
|
||
- Trocar de superfície **nos dois sentidos** na própria página (Câmara ↔ embed do YouTube), com o ponto da fala preservado ao voltar.
|
||
- Esperar a geração da Câmara **dentro do clique do player** (bounded), em vez de devolver "gerando" na primeira resposta; se estourar o orçamento, o "Tentar novamente" continua existindo e o estado honesto permanece.
|
||
- Nenhuma regressão nas saídas, na transcrição/posicionamento e na seleção/corte (C162/C166/C167/C172).
|
||
- **Guardrails:** nada de autenticar no YouTube nem embed novo; não inventar estado; a superfície que o app controla segue preferida (C178); transcrição/posicionamento e seleção/corte intactos; sem `Consent`/collection/migration; URLs públicas do acervo intocadas; crédito "Fonte: Câmara dos Deputados · CC BY 4.0" mantido.
|
||
|
||
## Dados (intenção)
|
||
|
||
- **Vou apresentar dados?** Não — é feedback de ação no player, não dado de acervo; nenhum KPI/gráfico novo.
|
||
- **Decisões desbloqueadas:** a assessoria decide seguir com a peça sem trocar de ferramenta; a coordenação decide, pelo uso, se o YouTube volta a ser superfície padrão algum dia.
|
||
- **Forma:** _adiada ao plano de implementação_ — restrição de produto: o estado do player é feedback de ação, nunca dado persistido.
|
||
|
||
## Dados da decisão (literais)
|
||
|
||
- **Duas políticas hoje (a raiz do defeito):** a do player `SPEECH_VOD_PLAYER_POLICY = { statusTimeoutMs: 15000, statusRetries: 1, retryDelayMs: 1000, pollAttempts: 0, pollDelayMs: 1000 }` — com `pollAttempts: 0`, o primeiro `GERANDO` já retorna `{state:'gerando'}`; a do corte `SPEECH_VOD_CUT_POLICY = { statusTimeoutMs: 45000, statusRetries: 1, retryDelayMs: 1000, pollAttempts: 2, pollDelayMs: 5000 }` — essa espera e por isso "funciona".
|
||
- **Copy pt-BR existente (manter):** bloco de saída "Se o vídeo não abrir aqui, assista por outro caminho:", botões "Abrir no YouTube" (link externo, no ponto) e "Assistir na Câmara"; estado de geração já nomeado "A Câmara está gerando o trecho"; retry "Tentar novamente".
|
||
- **Copy nova (proposta):** botão "Assistir no YouTube" no mesmo bloco de saída, no ponto da fala.
|
||
- **Embed do YouTube (contrato a preservar):** `https://www.youtube.com/embed/<id>?playsinline=1&rel=0&start=<segundos>`.
|
||
- Sem `Consent`/collection/migration; nada persistido no servidor.
|
||
|
||
## Direção no codebase (hipótese)
|
||
|
||
- **Áreas prováveis:** `src/components/campaign/speech/SpeechDetailPlayer.tsx` (setter simétrico de `surface` + botão no bloco de saída, `renderYoutubeExit`), `src/utilities/speech/speechVodResolver.ts` + a rota/action `.../comunicacao/acervo/resolver-vod` (`resolveSpeechVodForActor` hoje usa a política do player), `src/lib/speechShare.ts`.
|
||
- **Precedente a olhar:** C178 (`docs/plans/acervo-player-youtube-sem-parede-de-signin.md`, #1081) — redesenha a superfície padrão; `docs/plans/acervo-vod-sob-demanda.md` (C162/C169, a política do corte e a verificação de mídia).
|
||
- **Risco de acoplamento:** mesmo arquivo de C178/C172/C173 — serializar; pins em `tests/unit/speechDetailPlayer.unit.spec.tsx`, `tests/unit/speechVodResolver.unit.spec.ts` (fixa a política do player) e `tests/e2e/campaignSpeechAcervo.e2e.spec.ts` precisam ser renegociados no item.
|
||
|
||
## Dependências
|
||
|
||
- **Dura:** C178 — mesmo arquivo `SpeechDetailPlayer.tsx`; a superfície padrão precisa existir antes de dar a volta.
|
||
- **Suave:** C172/C173 — serializam no mesmo arquivo.
|
||
- Nenhum bloqueio de dados.
|
||
|
||
## Fora de escopo
|
||
|
||
- Fazer o YouTube tocar quando ele bloqueia; detectar/classificar a causa do bloqueio.
|
||
- Baixar/espelhar/transcodificar; tocar a superfície do VOD com um player novo.
|
||
- Tornar o YouTube a superfície padrão de novo (isso é C178).
|
||
- Segundo player/editor; exposição pública do acervo; `Consent`/collection/migration.
|
||
|
||
## Rabbit holes de produto
|
||
|
||
- **"Consertar o iframe do YouTube".** Se alguém "só completar": IFrame API, eventos, OAuth, player próprio. **Corte neste item:** a volta é um botão na nossa própria página; o YouTube continua embed anônimo.
|
||
- **Espera infinita / fila de render.** Se alguém "só completar": estado assíncrono persistido, cron, "avise quando ficar pronto". **Corte neste item:** orçamento curto dentro do clique; estourou → estado honesto + retry.
|
||
- **"Retry resolve, então é só mandar tentar".** **Corte:** isso é o defeito, não a solução — o app espera antes de acusar falha.
|
||
- **Redesenhar o player inteiro.** **Corte:** encaixe cirúrgico; transcrição, seleção e corte intactos.
|
||
|
||
## Questões em aberto (produto)
|
||
|
||
- **Quanto esperar dentro do clique do player?** **Opções:** A) reusar a política do corte (45s/2 polls de 5s) | B) política própria do player (ex.: alguns polls curtos) | C) manter `pollAttempts:0` e só melhorar a copy. **Recomendação:** B — um orçamento curto e próprio do clique, entre o imediato de hoje e o do corte, preservando o "bounded" e a verificação de mídia. _(assumido — validar com produto)_
|
||
- **O botão "Assistir no YouTube" aparece também no estado "gerando"?** **Opções:** A) sim, sempre que houver embed | B) só quando a superfície for `vod` e a mídia estiver resolvida. **Recomendação:** A — a saída é justamente o que falta hoje; nunca deixar o usuário sem caminho. _(assumido)_
|
||
- **Onde fica o botão?** **Opções:** A) no bloco de saída já existente | B) junto das ações do player. **Recomendação:** A — simétrico a "Assistir na Câmara", mesmo bloco, mesmo desenho.
|
||
|
||
## Referências
|
||
|
||
- GitHub Issue: —
|
||
- Planos irmãos: `docs/plans/acervo-player-youtube-sem-parede-de-signin.md` (C178), `docs/plans/acervo-vod-sob-demanda.md` (C162), `docs/plans/c171-player-youtube-sem-signin.md`
|
||
- Arquivos-chave (pista, não contrato): `src/components/campaign/speech/SpeechDetailPlayer.tsx`, `src/utilities/speech/speechVodResolver.ts`, `src/lib/speechShare.ts`, `src/app/(campaign)/campanha/actions/speech.ts`, `tests/unit/speechDetailPlayer.unit.spec.tsx`, `tests/unit/speechVodResolver.unit.spec.ts`, `tests/e2e/campaignSpeechAcervo.e2e.spec.ts`
|
||
- `AGENTS.md` / `AGENTS-campaign.md` — vertical Comunicação, gate do acervo e crédito CC BY
|
||
|
||
## Self-score (shaping)
|
||
|
||
5/5 — (1) fatia = um outcome verificável (volta simétrica ao YouTube + espera bounded na geração); (2) appetite ~0,5–1 dia comporta o controle simétrico e o ajuste de política, sem schema; (3) persona/job/aceite em linguagem de produto; (4) direção no codebase é hipótese com precedentes e arquivos nomeados; (5) zero decisão dura de engenharia (política, rota e shape do estado ficam para o plano de implementação).
|