20 KiB
Impl: Acervo: o preview de cada fala mostra um frame do meio daquela fala
Status: aprovado
Atualizado em: 2026-09-16
Issue: #1104
Intenção: docs/plans/acervo-preview-frame-do-meio-da-fala.md
Design UI: N/A — sem UI nova (o slot h-20 w-32 e o Skeleton são os de C175; só muda a origem da imagem)
Appetite restante: ~1–1,5 dia (herdado, sem corte)
Leitura da intenção
- Outcome: cada resultado da busca/lista do acervo mostra uma imagem da PRÓPRIA fala (um frame do meio,
excerptTMs + durationSeconds/2extraído do VOD da Câmara), não a capa da sessão; falas da mesma sessão deixam de repetir a mesma imagem. Sem VOD, cai na capa do YouTube (fallback honesto) — nunca imagem quebrada. - O que NÃO negociar (guardrails):
- Geração sob demanda e cacheada; nunca bloqueia a listagem (miniatura pequena,
lazy, sem CLS, estática — nada de player/hover-play). - Nada novo de Consent/LGPD e nenhuma exposição além do que a fala já expõe na lista (o VM não pode carregar a URL crua do VOD).
- O instante é
excerptTMs + durationSeconds/2; sem curadoria de frame, sem heurística de “frame feio”. corte/[id]público, o helperhqdefault(C179/#1093) e a busca/excerto/highlight ficam intactos;leader/advisorseguem fora do acervo.
- Geração sob demanda e cacheada; nunca bloqueia a listagem (miniatura pequena,
- O que reavaliar (hipóteses do plano):
- Elegibilidade:
speechVodCoordinatesexige um VOD armazenado (é o sinal do player,speechVod.ts:58-65). Para o poster, o critério honesto é ter as coordenadas do trecho na Câmara (eventId/audioId/excerptTMs) — senão a maioria das falas importadas (sem link cacheado) ficaria sem frame, contrariando o aceite. O VOD armazenado vira apenascachedUrls(ajuda, não habilita). - Disparo: geração síncrona num request de browser (imagem) não serve: o app está atrás do Cloudflare Tunnel (limite de ~100s por request) e o próprio repo trata trabalho longo com job em
after()+ poll (cortar+cortar/status,speechCutScheduler.ts:15-19). O desenho abaixo espera um teto curto e deixa a geração terminar em background. - Cache sem migration: o precedente
speechCut.mediaexige campo novo emSpeech(migration → hard-stop do modo autônomo). O cache vai por nome de arquivo determinístico namedia(zero schema).
- Elegibilidade:
Abordagem recomendada
flowchart LR
A["speechListSelect<br/>+ eventId/audioId/excerptTMs"] --> B["toSpeechListItemViewModel<br/>speechPosterTarget (coordenadas + duration/2)"]
B -->|"coordenadas + duração"| C["thumbnailUrl =<br/>/campanha/comunicacao/acervo/<id>/poster"]
B -->|"sem coordenadas"| D["youtubeThumbnailUrl(videoId)<br/>ou null"]
C --> E["<img loading=lazy><br/>SpeechResultThumbnail (inalterado)"]
E --> F["GET /[id]/poster<br/>gate canReadSpeechCatalog"]
F -->|"media cache hit"| G["302 media.url<br/>private, max-age=1d"]
F -->|"miss"| H["ensureSpeechPoster(id)<br/>single-flight + gate de concorrência"]
H -->|"pronto em ≤20s"| G
H -->|"ainda gerando"| I["after(): termina em background"]
F -->|"falha"| J["302 capa do YouTube<br/>no-store; senão 404"]
Opções consideradas: A) cache por nome determinístico em media + rota interna que gera sob demanda com espera curta e conclui em background (recomendada) | B) campo poster (relationship) em Speech + job | C) gerar no render do RSC ou job a cada listagem | D) manter hqdefault trocando só a variante.
Recomendação: A. Entrega o frame real da fala sem migration (hard-stop do modo), reusa Media + o proxy /api/media/file/..., resolveSpeechVod, downloadSource/runFfmpeg (extraídos do corte) e o slot C175 intacto. O <img loading="lazy"> só dispara para linhas na viewport, e a listagem nunca espera além do teto curto.
Rejeitadas: B — campo novo em coleção → migration e Issue blocked; C — RSC síncrono baixa/roda ffmpeg no caminho da página ou dispara N jobs por varredura (viola “nunca bloqueia”); D — é exatamente o defeito reaberto.
Decisões de engenharia
- Critério de elegibilidade — Opções: (A) coordenadas da Câmara (
eventId+audioId+excerptTMs) +durationSeconds > 0; (B)speechVodCoordinates(exige VOD armazenado); (C) sóyoutubeUrl. Recomendação: A — é o que o aceite pede (“fala com VOD da Câmara”); B deixa de fora falas resolvíveis mas nunca resolvidas, C é o defeito. Rejeitadas: B (sub-entrega silenciosa), C (defeito). - Onde a geração é disparada — Opções: (A) imagem aponta para uma rota interna que gera-e-cacheia; (B) no render da lista; (C) job a cada listagem. Recomendação: A — o RSC só monta a string da URL (puro); o browser pede só o que entra na viewport; uma geração por fala, cacheada. Rejeitadas: B (ffmpeg/download no caminho crítico), C (custo por varredura e miniatura neutra transitória).
- Latência do request de imagem — Opções: (A) espera curta (teto literal
SPEECH_POSTER_WAIT_MS = 20_000) e, se a geração não terminou, responde a capa enquanto ela continua em background viaafter(); (B) espera síncrona até completar; (C) sempre responder capa e só gerar em background. Recomendação: A — entrega o frame já na primeira varredura quando a geração é rápida, nunca encosta no teto do Cloudflare (~100s) e se auto-aquece quando é lenta. Rejeitadas: B (risco de 524 e request preso por minutos), C (a primeira varredura mostraria só a capa — o defeito). - Instante do meio — Opções: (A) baixar o MP4 do trecho (coordenadas em
excerptTMs) e extrair o frame emdurationSeconds/2; (B) pedir um trecho novo começando no meio e extrair em t=0. Recomendação: A — é literalmenteexcerptTMs + durationSeconds/2e reusa o pipeline do corte, cuja premissa (o trecho começa no início da fala) já é a despeechCutJob/C166. Rejeitada: B (transcodificação extra na Câmara e semântica do clipe menos previsível). - Cache sem migration — Opções: (A)
mediacom nome determinísticospeech-poster-<id>.jpg; (B) campoposteremSpeech; (C) disco/tmp. Recomendação: A —Mediajá existe,media.urljá é o proxy do bucket privado (ou disco em dev/test), e o nome é a chave de cache/idempotência. Rejeitadas: B (migration hard-stop), C (o container é recriado no deploy; prod é S3). - Como o cache é lido — Opções: (A) a rota procura
mediaporfilenamee responde302paramedia.url; (B) expor o id da mídia no VM. Recomendação: A — zero schema e o proxy existente faz o streaming. Rejeitada: B (vazaria o interior do cache no VM da lista e exigiria achar a mídia no loader). - Dedupe/corrida — Opções: (A) single-flight em memória + gate de concorrência +
withPayloadTransaction+acquireTextAdvisoryLocks(['speech-poster:<id>'])com re-checagem antes docreate; (B) só pré-checagem; (C) lock advisory cobrindo download/ffmpeg. Recomendação: A — o lock + re-checagem garantem nunca duas linhasmedia; download/ffmpeg ficam fora da transação (o lock não fica preso por minutos). Rejeitadas: B (linhas duplicadas sob concorrência), C (transação longa). - Proteção do homeserver (concorrência) — Opções: (A) gate simples in-process (
MAX_CONCURRENT_GENERATIONS = 2) + cache negativo curto (FAILURE_TTL_MS = 5min, que também memoriza osnullde "indisponível/gerando") por fala; (B) sem limite; (C) fila persistente. Recomendação: A — a varredura pede várias imagens de uma vez e o homeserver (8c/16GB, link compartilhado) não deve baixar 8 trechos em paralelo; o cache negativo evita repetir uma geração que acabou de falhar. Rejeitadas: B (rajada de downloads), C (fila nova é rabbit hole de produto). - Reuso do pipeline de mídia — Opções: (A) extrair
downloadSource/runFfmpegdespeechCutJob.tsparasrc/utilities/speech/speechMediaPipeline.tse importar nos dois; (B) copiar; (C) importarspeechCutJobno job do poster. Recomendação: A — mesma responsabilidade, dois call sites (“edit the owner, don't twin”). Rejeitadas: B (twin), C (acopla poster a corte). - Tamanho do still — Opções: (A)
-vf scale=480:-2 -frames:v 1 -q:v 2; (B) resolução cheia; (C)imageSizesnaMedia. Recomendação: A — dezenas de KB, sem tocar em schema/config. Rejeitadas: B (peso na listagem), C (migration hard-stop + afeta todos os uploads). - Contrato do VM — Opções: (A) manter
thumbnailUrl: string | nulle nele escolher frame vs capa; (B)posterUrlao lado dethumbnailUrl. Recomendação: A — o card tem um slot único; a escolha é do dono do link. Rejeitada: B (duas fontes concorrentes sem ganho). - Fallback — Opções: (A) falha →
302para a capa do YouTube quando houver, senão404(oonErrordeSpeechResultThumbnailjá assenta no slot neutro); (B) sempre404; (C) imagem quebrada. Recomendação: A — fallback honesto do aceite. Rejeitadas: B (perde reconhecimento parcial), C (proibida). - Testes — unit: helpers puros + VM; int: geração/cache e a fiação do loader; e2e: atualizar os pinos do acervo (o fixture tem coordenadas → passa a apontar para a rota). Rejeitadas: spec e2e novo; e2e buscar a rota (browserless — bateria na Câmara de verdade).
Componentes / mudanças
src/lib/speechPoster.ts(novo, puro/client-safe):speechPosterOffsetSeconds(durationSeconds)→floor(d/2)ounull;speechPosterTarget(speech)→{ eventId, audioId, excerptTms, offsetSeconds } | null(coordenadas da Câmara + duração num só dono, sem exigir VOD armazenado);speechPosterFilename(id)→speech-poster-<id>.jpg;speechPosterHref(id)→${CAMPAIGN_COMMUNICATION_ACERVO}/${id}/poster;buildSpeechPosterFfmpegArgs({ inputPath, outputPath, atSeconds })→['-nostdin','-hide_banner','-y','-ss',<at>,'-i',input,'-frames:v','1','-vf','scale=480:-2','-q:v','2','output].src/lib/speechVod.ts: extraispeechExcerptCoordinates(source)(as 3 coordenadas) e mantémspeechVodCoordinates = armazenado ? speechExcerptCoordinates : null— um dono para as duas leituras, sem mudar o contrato do player (speechVod.ts:58-65).src/utilities/speech/speechViewModels.ts:SpeechListRecordganha sóeventId?,audioId?,excerptTMs?(os links de VOD ficam fora da query da lista);toSpeechListItemViewModelmontathumbnailUrl = speechPosterTarget(speech) ? speechPosterHref(speech.id) : speechCoverUrl(speech.youtubeUrl). Nenhuma URL crua do VOD entra no VM. OspeechCoverUrl(novo emlib/speechVod.ts, composição deparseYoutubeVideoId+youtubeThumbnailUrl) é o mesmo usado pelo fallback da rota.src/utilities/speech/speechPageData.ts:33-46:speechListSelectganhaeventId,audioId,excerptTMs,vodPlaybackUrl,vodDownloadUrl(o loader já entrega a linha ao VM).src/utilities/speech/speechMediaPipeline.ts(novo,server-only):ffmpegBinary,downloadSource(url, destination),runFfmpeg(args, durationSeconds)e os literais de teto/timeout, extraídos despeechCutJob.ts:39-51,119-176sem mudança de comportamento.src/utilities/speech/speechCutJob.ts: passa a importar o pipeline extraído; remove as cópias locais.src/utilities/speech/speechPosterJob.ts(novo,server-only):findSpeechPosterMedia(payload, id);ensureSpeechPoster(payload, id)(single-flight por id + gate de concorrência + cache negativo; carrega a fala poroverrideAccess: truelendoeventId/audioId/excerptTMs/vod*/durationSeconds/youtubeUrl/speechAt;resolveSpeechVod(coords, { policy: SPEECH_VOD_PLAYER_POLICY, cachedUrls });downloadSource+buildSpeechPosterFfmpegArgs+runFfmpegemmkdtemp;withPayloadTransactioncomacquireTextAdvisoryLocks(['speech-poster:<id>'])+ re-checagem +payload.create({ collection:'media', data:{ alt }, filePath, overrideAccess:true, req });finallyremove o temp). O slot de concorrência é adquirido antes deresolveSpeechVod, então o teto cobre também a rede. Literais:SPEECH_POSTER_WAIT_MS = 20_000(exportado),MAX_CONCURRENT_GENERATIONS = 2,FAILURE_TTL_MS = 300_000.src/app/(campaign)/campanha/(app)/comunicacao/acervo/[id]/poster/route.ts(novo):export const dynamic = 'force-dynamic'; GET lêgetCampaignUser()e exigecanReadSpeechCatalog(senão404);ensureSpeechPosterjá cobre cache-hit (uma query) e miss;after()mantém o processo vivo ePromise.raceaplica o teto; frame →302comLocationrelativa (media.urlou a capa absoluta) — não resolvida contrarequest.url, que atrás do túnel carrega host interno — eCache-Control: private, max-age=86400; sem frame →302capa do YouTube (se houver) ou404, comCache-Control: no-store. Rota interna — nenhum contrato de URL pública muda.src/components/campaign/speech/SpeechResultThumbnail.tsx: sem mudança funcional; só o comentário doeslint-disabledeixa de dizer só “YouTube cover”.- Migration: sem migration. (Campo
posteremSpeechouimageSizesemMediaseria hard-stop → Issueblocked.) - Access / Consent: nenhum novo; a rota reusa
canReadSpeechCatalog; a escrita emmediaé bypass admin intencional, como o job de corte (a linha nasce atrás do gate do acervo). - UI: Impeccable A — sem trigger de designer (a/b/d): nenhuma superfície, layout, estado ou token novo; o slot e o
Skeletonsão os de C175.
Dados → forma
Não se aplica. Não nasce agregado, contagem, gráfico ou tabela: é a origem de uma imagem derivada de campos existentes (excerptTMs, durationSeconds, coordenadas da Câmara). A intenção já fecha “Vou apresentar dados? Não”.
Fases verificáveis
- Puro (unit-first):
lib/speechPoster.ts+ o refactorspeechExcerptCoordinates; testestests/unit/speechPoster.unit.spec.ts(offset, filename, href, args com-frames:v 1/scale=480:-2, elegibilidade) e os casos dethumbnailUrlemtests/unit/speechViewModels.unit.spec.ts. Verificação:pnpm test:unit -- speechPoster speechVod speechViewModelsverde. - Pipeline + job + VM/select: extrair
speechMediaPipeline, ajustarspeechCutJob, criarspeechPosterJob, estenderspeechListSelect/VM. Verificação:pnpm test:int -- speechCut speechAcervo speechPosterverde (o corte segue idêntico após a extração). - Rota + e2e + entrega: rota
[id]/poster, ajuste dos pinos do acervo,pnpm gate:fast,pnpm test:e2e:affected(campaignSpeechAcervo+campaignSpeechCut), entrega compnpm push.
Rabbit holes / Não escopo (engenharia)
- Backfill/mirroring de posters; gerar para falas sem coordenadas da Câmara.
- Curadoria manual do frame ou heurística de “frame ruim → capa” (a intenção adia; reavaliar com uso real).
- Tocar em
corte/[id]público, no player ou na capa de corte; consolidar o helperhqdefault(C179/#1093). - Player/hover-play,
next/image,blurDataURL,remotePatterns. - Collection/fila/worker novos; qualquer migration de schema.
Riscos e mitigação
- Timeout do Cloudflare (~100s): o request de imagem nunca espera mais que
SPEECH_POSTER_WAIT_MS; a geração continua emafter(); nada de 524 preso. - Primeira varredura parcial: falas cuja geração passa do teto mostram a capa nesta visita e o frame nas seguintes (o cache já foi gravado). É o custo de “sob demanda e cacheado”; revisitar com o gatilho abaixo se o produto exigir frame na primeira visita (caminho: retry no cliente ou aquecimento no loader).
- Rajada no homeserver: gate de concorrência (2) +
lazy+ cache negativo; no pior caso, trabalho duplicado uma vez, nunca linha/arquivo duplicado. - Download grande para uma miniatura: teto de bytes/timeout herdados (
MAX_SOURCE_BYTES,SOURCE_DOWNLOAD_TIMEOUT_MS), seek de entrada (-ssantes de-i, barato em arquivo local) e uma geração por fala. - Órfão no bucket S3: se a transação falhar após o upload, o objeto pode ficar sem linha (mesmo comportamento aceito do C167); se o adapter renomear por colisão, a rota regenera — custo, não corrupção.
- Poluição da biblioteca
media: cada poster cria uma linha derivada (speech-poster-*), visível no admin de mídia. Aceito nesta entrega (marcarsource/collection própria exige migration); gatilho: a lista de mídia do admin ficar ruidosa. - Câmara indisponível/
GERANDO: fallback para a capa ou404(slot neutro); sem cache negativo eterno (TTL curto) e nova tentativa depois. - Vazamento do VOD cru no VM: o job lê
vod*só paracachedUrls(fora da query da lista); o VM de lista nunca os recebe — coberto por asserção no int. - Leitura pública do frame derivado:
Media.readé() => truee o nome é determinístico (speech-poster-<id>.jpg), então quem adivinhar o nome alcança o JPEG no proxy de mídia, fora do gate do acervo. Conteúdo = frame de sessão pública da Câmara, sem PII nem VOD cru; aceito nesta entrega e registrado como risco (a alternativa — rota gated streamando bytes — é mais código e não muda a natureza pública do vídeo-fonte). excerptTMs/durationSecondsausentes: coordenadas ou offsetnull→ capa/slot neutro.
Aceite de engenharia
- Aceite de produto da intenção coberto: fala com coordenadas da Câmara mostra frame do meio; falas da mesma sessão divergem; sem coordenadas mantém a capa (ou slot neutro); nunca imagem quebrada; miniatura
lazy, sem CLS e sem bloquear a listagem. - Invariantes AGENTS/engineering-standards: identificadores em inglês, sem migration/Consent/access novos, rota interna (URL pública intacta),
overrideAccess:falsenos reads comuser, bypass admin intencional documentado nos writes do sistema, transação +reqna escrita. - Sem migration; se exigida, Issue
blocked(hard-stop do modo). - Testes de domínio previstos: unit cobre os helpers puros + VM; int prova geração/cache/single-flight/cache negativo e o corte segue verde após a extração; e2e do acervo atualizado (lista + rota).
pnpm gate:fastverde;pnpm test:e2e:affectedverde (campaignSpeechAcervo+campaignSpeechCut); entrega viapnpm push.
Self-score (decision-quality)
4.5/5 — (1) as decisões caras (cache sem migration, elegibilidade, latência do request, dedupe/lock, reuso do pipeline) têm opções e rejeitadas explícitas; (2) cabe no appetite ~1–1,5 dia (um módulo puro, uma extração mecânica, um job e uma rota fina); (3) rabbit holes nomeados (backfill, curadoria de frame, corte/[id], C179, migration) e o hard-stop tratado; (4) depth check: reusa Media/proxy, resolveSpeechVod, withPayloadTransaction/acquireTextAdvisoryLocks e o pipeline extraído do corte — sem collection/fila/worker novos; (5) a intenção permanece satisfeita — o frame do meio da fala sem reescrever o outcome nem o fallback honesto.
Débitos deferidos (capture-review-debts)
- Registrado — C185 (
docs/plans/escala-dry-pos-c182.md,depends: C182): F1 poster obsoleto quandodurationSeconds/excerptTMsmudam (nome do cache não carrega o offset) + F2 prova automatizada do estouro do teto e doCache-Controldo fallback. - Defer com gatilho — D1 (primeira varredura parcial): fala lenta mostra a capa nesta visita e o frame na seguinte. Gatilho: produto exigir frame na 1ª visita (retry no cliente ou aquecimento no loader).
- Defer com gatilho — D2 (poluição da
media): cada fala vista cria uma linhaspeech-poster-*. Gatilho: a lista de mídia do admin ficar ruidosa (marcador de origem exigiria migration). - Defer com gatilho — D5 (órfão S3 / rename por colisão): objeto sem linha ou regeneração por custo. Gatilho: órfãos crescendo no bucket.
- Defer com gatilho — D7 (gate in-process): multiplicaria com múltiplas réplicas. Gatilho: scale-out acima de um container.
- Descartado — D3 (frame derivado publicamente legível): decisão travada (conteúdo de sessão pública, sem PII/VOD cru); a alternativa gated foi rejeitada no plano.
Já resolvido no /simplify (não reabrir)
vod*fora da query da lista; cache negativo cobrindo osnullde indisponível/gerando; slot de concorrência antes deresolveSpeechVod;rmdo temp antes de liberar o slot;Locationrelativa no 302 (host interno atrás do túnel);speechPosterTargetespeechCoverUrlcomo donos únicos;runFfmpegcom a copy de fallback do dono; poda do mapa de falhas; tipagem viaPayloadTransactionRequest; testes de single-flight (1 chamada à API da Câmara) e do cache negativo.