10 KiB
Impl: 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 Intenção: docs/plans/acervo-player-volta-ao-youtube-e-vod-com-espera.md Appetite restante: ~0,5–1 dia eng (herdado da intenção); nada mais entra.
Leitura da intenção (outcome, não negociar, reavaliar)
- Outcome: trocar de superfície nos dois sentidos (Câmara ↔ YouTube) na mesma página, com ponto da fala preservado; esperar geração da Câmara dentro do clique do player (bounded) em vez de devolver "gerando" na primeira resposta.
- O que NÃO negociar: nada de autenticar no YouTube nem embed novo; não inventar estado; 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.
- O que reavaliar: hipóteses de "Direção no codebase" que podem estar erradas.
Abordagem recomendada
flowchart LR
U[clica em "Assistir na Câmara"] --> R[resolveSpeechVod com política do player<br/>pollAttempts: 2, pollDelayMs: 3000]
R --> G{resposta da Câmara?}
G -- PRONTO --> P[<video> toca o trecho]
G -- GERANDO --> W[espera bounded<br/>polls curtos]
W --> G
G -- INDISPONIVEL/estourou --> F[estado honesto + "Tentar novamente"]
P --> E[bloco de saída "Assistir no YouTube" sempre visível]
F --> E
Opções consideradas:
- A — Trocar
pollAttempts: 0porpollAttempts: 2compollDelayMs: 3000noSPEECH_VOD_PLAYER_POLICY(reusar a lógica de polling já existente noresolveFromVodApi). - B — Criar uma política nova
SPEECH_VOD_PLAYER_POLLING_POLICYcom valores próprios. - C — Manter
pollAttempts: 0e só melhorar a copy.
Recomendação: A — a lógica de polling já existe e é testada; basta ajustar os parâmetros da política do player. Rejeitadas: B (complexidade desnecessária; uma política por caller é suficiente), C (não resolve o defeito).
Componentes / mudanças
-
src/utilities/speech/speechVodResolver.ts(editar o dono):- Trocar
SPEECH_VOD_PLAYER_POLICY.pollAttemptsde0para2. - Trocar
SPEECH_VOD_PLAYER_POLICY.pollDelayMsde1_000para3_000. - Justificativa: 2 polls de 3s = até 6s de espera adicional (total ~9s com o primeiro fetch); é um orçamento curto e próprio do clique, entre o imediato de hoje e o do corte (45s/2 polls de 5s).
- Trocar
-
src/components/campaign/speech/SpeechDetailPlayer.tsx(editar o dono):- O bloco
renderYoutubeExit()já existe e é sempre visível (C178); não precisa de mudança. - O estado
generatingjá mostra "A Câmara está gerando o trecho" e "Tentar novamente"; com o polling ativo, o player vai transitar automaticamente degeneratingpararesolved(oufailedse estourar o orçamento). - Nenhuma mudança de UI necessária — o defeito é na política de polling, não no componente.
- O bloco
-
src/app/(campaign)/campanha/actions/speech.ts(não mexer):resolveSpeechVodForActorjá usaresolveSpeechVod(coordinates)que por padrão usaSPEECH_VOD_PLAYER_POLICY; a mudança na política surte efeito automaticamente.
-
src/lib/speechVod.ts(não mexer):- A função
resolveFromVodApijá suportapollAttempts > 0; não precisa de mudança.
- A função
-
Migration: sem migration — mudança de constante em código, não de schema.
-
Access / Consent: sem mudança.
-
UI: Impeccable A — N/A (sem UI nova; o bloco de saída já existe e é sempre visível).
-
Testes:
tests/unit/speechVodResolver.unit.spec.ts: atualizar o pin deSPEECH_VOD_PLAYER_POLICY(linha 164-171) para refletir os novos valores.tests/unit/speechDetailPlayer.unit.spec.tsx: adicionar teste para o estadogeneratingcom polling ativo (mockar fetch para retornarGERANDOna primeira chamada ePRONTOna segunda; verificar que o player transita pararesolved).tests/e2e/campaignSpeechAcervo.e2e.spec.ts: o teste existente "search keeps the download off the card; the both-sources detail defaults to the Câmara excerpt" já cobre o estado idle; não precisa de mudança.
-
Changelog:
docs/changelog/2026-09-16-c181.md.
Dados → forma (a resposta é a superfície)
- Forma escolhida: a mudança é transparente para o usuário; o player agora espera a geração da Câmara antes de anunciar "gerando/falhou".
- Rejeitadas: UI nova (anti-goal), embed do YouTube (anti-goal), autenticação (anti-goal).
Decisões de engenharia
D1 — Política de polling do player: reusar a lógica existente com parâmetros próprios
- Opções: A) ajustar
SPEECH_VOD_PLAYER_POLICY(pollAttempts: 2, pollDelayMs: 3000) | B) criar política nova | C) manter pollAttempts: 0. - Recomendação: A — reusa código testado, cumpre o orçamento curto do clique, não inventa estado.
- Rejeitadas: B (complexidade desnecessária), C (não resolve o defeito).
D2 — Visibilidade do bloco de saída "Assistir no YouTube"
- Opções: A) manter como está (sempre visível quando youtubeWatchUrl existe) | B) mostrar só quando a superfície for
vode a mídia estiver resolvida. - Recomendação: A — a saída é justamente o que falta hoje; nunca deixar o usuário sem caminho.
- Rejeitadas: B (restringe a saída no momento em que mais se precisa dela).
D3 — Localização do botão "Assistir no YouTube"
- Opções: A) no bloco de saída já existente (
renderYoutubeExit) | B) junto das ações do player. - Recomendação: A — simétrico a "Assistir na Câmara", mesmo bloco, mesmo desenho.
- Rejeitadas: B (desconecta a saída do contexto de "outro caminho").
Fases verificáveis
- Ajuste da política (~0,1 dia): editar
SPEECH_VOD_PLAYER_POLICYemsrc/utilities/speech/speechVodResolver.ts(pollAttempts: 2, pollDelayMs: 3000). Prova:pnpm test:unitverde (pin atualizado no spec). - Teste do polling no player (~0,25 dia): adicionar teste em
tests/unit/speechDetailPlayer.unit.spec.tsxque mockia fetch para retornar GERANDO → PRONTO e verifica a transição. Prova: spec novo verde. - Verificação e2e (~0,1 dia): rodar
pnpm test:e2e --grep "acervo"para garantir que nenhum quadrante quebrou. Prova: e2e verde. - Changelog e lint (~0,05 dia): criar
docs/changelog/2026-09-16-c181.md, rodarpnpm lintepnpm format:check.
Quota total: ~0,5 dia (dentro do appetite herdado).
Rabbit holes / Não escopo (engenharia)
- Trocar a superfície do YouTube para embed. Corte: a volta é um botão na nossa própria página; o YouTube continua embed anônimo.
- Espera infinita / fila de render. Corte: 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.
- Autenticar no YouTube ou usar embed novo. Corte: anti-goal explícito na intenção.
- Inventar estado ("sucesso" sem verificação de mídia). Corte: a política de probing já verifica a mídia antes de devolver
pronto. - Mudar o bloco de saída "Assistir no YouTube". Corte: já existe e é sempre visível (C178); não precisa de mudança.
Riscos e mitigação
- A Câmara demora mais que 9s para gerar o trecho: o player entra no estado
generatinge mostra "Tentar novamente" (estado honesto); o usuário pode clicar retry manualmente. Mitigação: o orçamento de 9s cobre a maioria dos casos; se a Câmara ficar lenta frequentemente, reavaliar opollAttempts. - Regressão nos testes existentes: o pin de
SPEECH_VOD_PLAYER_POLICYno spec precisa ser atualizado. Mitigação: atualizar o pin antes de rodar os testes. - Mudança de comportamento para usuários existentes: o player agora espera 9s em vez de falhar imediatamente; isso é uma melhoria, não um defeito. Mitigação: nenhum usuário vai reclamar de "esperou demais" quando antes falhava de primeira.
Aceite de engenharia
- Aceite de produto da intenção coberto: o player sempre deixa voltar ao YouTube (bloco de saída sempre visível) e espera a geração da Câmara dentro do clique (pollAttempts: 2, pollDelayMs: 3000).
- Invariantes AGENTS/engineering-standards:
overrideAccess: false+userem toda leitura; gatecanReadSpeechCatalog; sem migration/Consent; sem UI nova; identificadores em inglês, chaves/copy em pt-BR. - Testes previstos: unit
speechVodResolver(pin atualizado) +speechDetailPlayer(transição generating→resolved) + e2ecampaignSpeechAcervo(quadrantes intactos);pnpm lintepnpm format:checkverdes. - Changelog:
docs/changelog/2026-09-16-c181.md.
Self-score decision-quality: 5/5 — (1) fatia = um outcome verificável (volta simétrica ao YouTube + espera bounded na geração); (2) appetite ~0,5 dia comporta o ajuste de política e os testes, sem schema; (3) persona/job/aceite em linguagem de produto; (4) direção no codebase é precisa (arquivos nomeados, política existente, bloco de saída já implementado); (5) zero decisão dura de engenharia (política e UI já existem; só ajuste de parâmetros).
- Decisões caras com rejeitadas: 3/3 — D1 (política), D2 (visibilidade da saída), D3 (localização do botão) no formato Opções|Recomendação|Rejeitadas.
- Cabe no appetite? 5/5 — ~0,5 dia (dentro do herdado); sem migration, sem UI, sem dependência nova.
- Rabbit holes nomeados? 5/5 — embed do YouTube, espera infinita, retry como solução, redesign do player, autenticação, inventar estado, mudança de UI.
- Depth check reusa? 5/5 —
resolveFromVodApijá suporta polling,renderYoutubeExitjá existe e é sempre visível,speechVodResolverjá exporta a política,speechDetailPlayerjá tem o estadogenerating. - Intenção permanece satisfeita? 5/5 — o outcome não foi reescrito: a volta ao YouTube é simétrica (bloco de saída sempre visível) e a espera é bounded (pollAttempts: 2, pollDelayMs: 3000).