Clipador: vídeo final sem camadas de teste ao aprovar; publicação só usa o final

Pedido do dono: o vídeo da fila é de revisão (com as camadas `dev`, ex.: tradução);
ao aprovar, o serviço renderiza de novo sem elas, e só esse vai para as redes.

- db v14: clips.review_dev_json (camadas que entraram na revisão) e final_status/
  final_file/final_thumb/final_cover/final_error/final_at; backfill dos cortes antigos.
- Motor: queue_final/drop_final/render_final; fila renderiza finais primeiro com
  render_clip_edit(dev=False) em clip-<id>-final.mp4; revisão sem camada de teste
  vira o final sem render novo; prune guarda os blocos de quem ainda precisa do final.
- API: clip traz review.devLayers, final e publishFile; aprovar enfileira o final;
  desaprovar, mudar trecho, exportar, re-render e rejudge derrubam o final;
  POST /v1/clips/{id}/final (tentar de novo).
- Painel: etiqueta na lista, player Final/Revisão e estado do final no modal
  (gerando/pronto/erro com "Tentar de novo"), aviso no "Publicar"; o despachante
  relê o corte antes de enviar e espera o final (clipPublishFile), nunca a revisão.
- Testes: clipper/tests/test_final_render.py e testes do despachante no painel.
- Doc: doc/clipador/REVISAO.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Mateuus
2026-11-18 03:27:26 -03:00
co-authored by Claude Opus 5.5
parent 54eac7cebf
commit dc0917b114
16 changed files with 819 additions and 23 deletions
+85
View File
@@ -0,0 +1,85 @@
# Clipador — vídeo de revisão × vídeo final
Pedido do dono (18/11/2026):
> Quando o clipe está ali para a gente aprovar, a legenda é só de dev. Quando a gente aprovar, ele vai renderizar o
> vídeo de novo, removendo as coisas de dev.
## Fluxo
```
fila de render ─► VÍDEO DE REVISÃO clip-<id>.mp4 (dev=True: entram as camadas `dev` ligadas)
│ status ready → equipe assiste e decide
▼
Aprovar (PATCH status=approved|published)
│
review_dev_json = []? ──sim──► o de revisão JÁ É o final (sem render novo; final.reused = true)
│não / não se sabe
▼
VÍDEO FINAL clip-<id>-final.mp4 (+ -final.jpg, -final-cover.jpg) (dev=False)
│ final_status: pending → rendering → ready | error
▼
Publicação: SÓ `publishFile` (o final pronto); sem ele, o envio espera
```
- **Camadas `dev`** (`layout.py`, grupo `dev` da configuração do corte): hoje `translation` (português embaixo da
legenda) e `dub` (dublagem em português). `layout.dev_flags(cfg, dev=False)` desliga todas.
- O render da fila (`worker._render_clip` → `editor_api.render_clip_edit(..., dev=True)`) grava em
`clips.review_dev_json` quais camadas entraram de fato (`editor_api.review_layers`): a tradução só conta se havia
frases para desenhar (fonte em português nunca tem); as outras chaves contam pela configuração, por cautela.
- O final roda na mesma fila do motor (`Engine.render_pending`: finais primeiro, até 3 por volta), com
`render_clip_edit(..., dev=False)` sobre o MESMO projeto de edição. Não pede tradução, não grava `review_dev_json`.
- Falha no final vira `final_status = 'error'` com `final_error`; o corte continua aprovado e nada é publicado.
Serviço caiu no meio: na subida `rendering` volta a `pending`.
## O final deixa de valer quando…
| Ação | Efeito |
| --- | --- |
| Desfazer aprovação / rejeitar (`PATCH status=ready|rejected`) | final some (`drop_final`); aprovar de novo gera outro |
| Mudar início/fim de um aprovado (`PATCH startS/endS`) | volta para `pending` (revisão nova) e o final some |
| Exportar do editor (`POST /export`), re-render (`POST /render`), mandar de novo para a IA (`POST /rejudge`) | final some; o corte volta a ser revisão e precisa ser aprovado de novo |
| Qualquer render de revisão novo terminar | final some (conteúdo novo) |
| Desaprovar DURANTE o render do final | o resultado é descartado (só grava se ainda estiver `rendering`) |
O arquivo `clip-<id>-final.mp4` antigo fica no disco até o próximo final (mesmo nome) ou até apagar o corte
(`clip_delete` apaga `clip-<id>-*`). Apagar é recusado enquanto o final renderiza.
**Limpeza dos blocos** (`CLIPPER_KEEP_HOURS`): além dos cortes em andamento, `prune` guarda o trecho de quem ainda vai
precisar do final — aprovado com final `pending`/`rendering`/`error`, e pronto para aprovar cujo vídeo de revisão tem
camada de teste (ou não se sabe). Corte pronto **sem** camada de teste não segura blocos (o de revisão já é o final).
## Banco (migração v14, `clipper/app/db.py`)
`clips.review_dev_json` (JSON: `["translation", …]`; `[]` = nenhuma; NULL = desconhecido) · `final_status`
(`pending|rendering|ready|error`; NULL = sem final) · `final_file` · `final_thumb` · `final_cover` · `final_error` ·
`final_at`. Cortes antigos: sem `translation_json` → `review_dev_json = []` (a tradução era a única camada); aprovados
assim ganham o final = o próprio arquivo; aprovados com tradução ficam `pending` (renderiza na subida); publicados com
tradução ficam sem final (gera com `POST /final` se forem para outra rede).
## API (`/v1/clips…`)
- Cada corte traz `review: {devLayers}`, `final: {status, file, thumb, cover, error, at, reused} | null` e
`publishFile` = `final.file` quando o corte está `approved|published` e o final está `ready`; senão `null`.
`file`/`thumb` continuam sendo os do vídeo de revisão.
- `POST /v1/clips/{id}/final` — (re)gera o final de um corte aprovado ("Tentar de novo"); 409 se não aprovado.
## Publicação (painel)
- `panel/src/lib/publishing-rules.ts` → `clipPublishFile(clip)`: devolve `publishFile` ou o motivo de esperar. Nunca
devolve `file` quando o Clipador manda o campo (Clipador antigo, sem `publishFile`, segue com `file`).
- `publishing.ts → sendDue`: antes de mandar um job de corte ao Publicador, relê o corte no Clipador
(`clipFinalForJob`); sem final pronto o job fica na fila com o passo "Esperando o vídeo final…"; com o final, troca
`file` (e a capa, se o final tiver) do job e envia. O arquivo gravado ao criar o job é só referência.
- Capa do corte (`clipCover`): a do final primeiro.
## Painel (`/clipper`)
- Lista: etiqueta `revisão · teste` (vídeo com camadas de teste), `gerando final`, `final` ou `final com erro`.
- Modal: o player toca o final quando existe (botões **Final / Revisão** para comparar); texto dizendo se é o de
revisão (e quais camadas de teste) ou o final; estado do final depois de aprovar (na fila/gerando… · pronto · erro com
**Tentar de novo**); aprovado sem final: **Gerar vídeo final**.
- Diálogo "Publicar": aviso de que o envio espera o vídeo final enquanto ele não está pronto.
Testes: `clipper/tests/test_final_render.py`; `panel/src/lib/publishing-rules.test.ts` (regra) e
`publishing-db.test.ts` (despachante espera o final e envia o arquivo final).