Appearance
Arquitetura do atpares-shorts
Estado: proposta de integração suspensa em 30/09/2026. O escopo atual fica isolado em atpares-shorts; nada desta topologia será implementado no dashboard ou na API Atpares nesta fase. A assinatura Pro será usada na interface do Flow, sem ativar API de vídeo com cobrança separada.
Objetivo e fronteiras
Produzir vídeos verticais complexos no Google Flow usando os créditos da conta Google AI Pro do operador, baixá-los como MP4 e associá-los a uma publicação do Atpares. A escolha do motor ocorre por publicação: flow_web ou remotion. O Atpares conserva a pauta, o texto social, a aprovação, o armazenamento e a publicação. O Flow produz a peça audiovisual completa. O serviço novo faz a ponte entre os dois.
O primeiro escopo cobre uma conta Google operadora, uma sessão de navegador e uma geração por vez. Não é uma API pública de vídeo, um serviço multiusuário Google nem uma integração com a Gemini API. Não promete que o Flow gere texto, narração ou legendas perfeitos: a peça final passa por revisão humana. Como essa única conta paga os créditos de vários projetos possíveis, a API mantém uma lista explícita de projetos autorizados a usar flow_web e um teto agregado diário/mensal definido pelo operador. Proprietário do projeto não ganha acesso ao Flow apenas por ter acesso ao Atpares.
Estado atual no workspace
| Local | Comportamento atual | Mudança planejada |
|---|---|---|
atpares-api/apps/api/src/modules/publications/publications.service.ts | short_video chama runVideo e Remotion | Desviar apenas flow_web para um job durável; evitar geração duplicada |
atpares-api/apps/api/src/modules/publications/publications.controller.ts | POST :id/video inicia Remotion; GET :id/video lê MP4 | Expor escolha do motor, estado, candidato e aprovação |
atpares-api/apps/api/src/modules/publications/publications.repository.ts | video e videoKey guardam o ativo final | Manter essas colunas; acrescentar origem e job/candidato separados |
atpares-api/apps/api/src/modules/integrations/media-publisher.service.ts | Lê videoKey para publicar Reel | Reutilizar sem mudar a publicação nas redes |
atpares-app/src/modules/projects/components/CoverCard.vue | Botão gera vídeo com Remotion | Mostrar origem, início, progresso, prévia e aprovação do Flow |
atpares-infra/docker-compose.atpares.yml | API e Redis na rede privada atpares | Adicionar worker com volume privado para perfil do navegador |
Hoje o progresso de geração de publicação fica em memória na API. Jobs de Flow podem durar muito e sobreviver a reinícios; por isso seu estado precisa ser persistido no banco. As notificações existentes podem espelhar o estado, mas não ser sua fonte de verdade.
Topologia
mermaid
flowchart LR
UI[Atpares App] -->|autenticação do usuário| API[Atpares API]
API --> DB[(Postgres: video_jobs)]
API -->|job autenticado, rede privada| W[atpares-shorts]
W -->|Playwright + Chromium| FLOW[Google Flow]
FLOW -->|download da sequência| W
W -->|PUT temporário assinado| S3[(S3: candidatos)]
W -->|evento autenticado| API
API -->|validação e aprovação| S3
API -->|videoKey aprovado| PUB[Publicador atual]
API -->|estado e prévia| UIO worker fica apenas na rede Docker privada atpares; não ganha domínio público. Somente a API autentica usuários e autoriza ações. O worker recebe apenas dados do job, referências temporárias e um token de serviço. Ele não recebe tokens das redes sociais nem acesso ao banco. O navegador usa a saída de rede do container para acessar o Google; o perfil e os downloads ficam em volume privado com permissões restritas.
Fluxo principal
- A API verifica proprietário, publicação não publicada, texto salvo e motor
flow_web. Salva uma revisão imutável do briefing com roteiro por cena, referências, proporção 9:16, duração alvo, idioma, direção de som e limites de gerações/créditos. O trabalho é criado comoqueuedantes do envio. - O dispatcher envia um job idempotente ao serviço. Se o envio falhar, o job continua em
queuede pode ser reenviado após reinício. - O worker assume a única vaga de navegador, confirma sessão válida e verifica se a interface do Flow permite executar o plano. Se login/MFA ou um diálogo desconhecido aparecer, marca
needs_operator; não tenta contornar desafio. - O adaptador cria ou retoma um projeto Flow identificado no job, envia referências, gera os clipes e registra IDs/URLs de interface quando observáveis. Antes de cada geração, aplica o orçamento configurado.
- O adaptador monta a sequência no Scenebuilder, exporta o MP4 e confere a existência e o término do download. Não depende de URL interna de mídia.
- O worker envia o MP4 para uma chave de candidato por URL assinada de curta duração. A API confere MIME real, contêiner, codecs, resolução, proporção, duração, áudio, tamanho e checksum. Falha de validação não toca o vídeo atual.
- A UI apresenta o candidato, custo observado quando disponível e checklist editorial. Só a aprovação humana promove o MP4 para
videoKey, atualizavideopara o formato reconhecido pelo publicador e libera a publicação.
O candidato é imutável. Regerar cria outro job e outro candidato. O ativo publicado nunca é sobrescrito. Se a publicação mudar durante a execução, o hash do briefing deixa o resultado stale; a revisão não pode aprová-lo sem uma decisão explícita de recriar o job para o conteúdo atual.
Trocar o motor ou editar conteúdo que altera o vídeo invalida a aprovação do ativo atual: a API limpa o marcador video/videoKey da publicação e conserva o objeto antigo apenas no histórico. A troca mostra essa consequência no painel. Assim, a rotina de publicação não envia um vídeo feito para uma versão anterior da pauta.
Escolha do motor
Introduzir videoEngine = remotion | flow_web na publicação, com padrão remotion para compatibilidade. A escolha deve ocorrer antes da etapa de mídia automática. A seleção flow_web impede a chamada atual de runVideo; ela cria o job apenas após a pauta/texto estarem fechados. Em publicações criadas pela automação semanal, a política inicial é não iniciar Flow automaticamente: ela cria a pauta e deixa o job para aprovação humana, pois cada geração consome créditos e a interface pode pedir intervenção. A política poderá ser ampliada depois de medir confiabilidade e custo.
video continua um marcador de ativo aprovado (reel/short conforme o contrato existente), não o nome do provedor. A origem fica em campo próprio. O publicador atual exige mediaFormat=short_video e video preenchido, e lê videoKey; não deve publicar um candidato.
Dados duráveis propostos
publication_edits: video_engine, video_origin, current_video_job_id. video_assets: versões imutáveis aprovadas ou substituídas, com publication_id, engine, object_key, briefing_hash, job_id opcional, status e datas. Ao invalidar videoKey, o arquivo continua rastreável nessa tabela. O histórico existente video_versions continua específico do roteiro e render do Remotion. video_jobs:
| Campo | Uso |
|---|---|
id, project_id, publication_id, owner_id | Escopo e autorização da API |
engine, state, attempt, idempotency_key | Execução e retomada |
briefing_json, briefing_hash | Snapshot imutável; sem senha ou cookie |
flow_project_ref, flow_scene_ref | Retomada best effort; dados opacos da UI |
candidate_key, sha256, media_metadata_json | Arquivo de revisão e prova de integridade |
credit_budget, credit_usage_observed | Teto por job e prestação de contas |
error_code, error_summary, created_at, updated_at, lease_until | Recuperação e diagnóstico |
Não persistir credenciais Google, cookies, conteúdo completo de sessão ou URLs assinadas no banco. Migrações e tipos devem entrar no atpares-api quando a implementação começar.
Dependências e decisões
- Configuração: somente
SHORTS_SERVICE_TOKEN,FLOW_GOOGLE_EMAILeFLOW_GOOGLE_PASSWORDficam no.env. Porta4320, API internahttp://atpares-api:4310, perfil/data/browser-profile, artefatos/data/artifacts, concorrência1e navegador com display virtual são constantes do serviço. Testes injetam dependências sem criar outras variáveis de ambiente. Mudanças de topologia exigem alteração versionada de código e do compose. - Navegador: Playwright com Chromium em container com display virtual. Seletores preferem papel/nome acessível; mudanças da UI disparam erro identificado e evidência visual redigida, sem adivinhar cliques.
- Sessão: perfil persistente em volume exclusivo do worker. Login interativo inicial e renovação manual quando Google solicitar. Variáveis de e-mail/senha são opcionais para bootstrap; não são garantia de login sem intervenção.
- Fila: Postgres é a fonte de verdade. O dispatcher pode usar Redis/BullMQ já presente no Atpares para entrega, mas cada mensagem carrega apenas
jobId; lease e idempotência são conferidos no banco. - Mídia: upload direto a S3 com URL PUT assinada emitida pela API. O worker não guarda credenciais S3. A API valida o objeto antes de oferecer aprovação.
- Retomada: após reinício, jobs com lease expirado voltam a
queuedouneeds_operator. Nunca repetir uma geração que pode ter gasto créditos sem antes reconciliar o projeto Flow ou pedir decisão humana. - Implantação: serviço privado no compose de
atpares-infra, logs sem prompts sensíveis, senhas, cookies ou links de sessão. Health distingue processo vivo, navegador funcional e sessão autenticada.
Limites e condições de viabilidade
O Flow documenta clipes, proporção, Scenebuilder e download, mas não documenta uma API/CLI para consumir créditos da assinatura Pro. O adaptador será frágil frente a mudanças na interface. Não chamar endpoints privados, falsificar requisições internas, contornar CAPTCHA/MFA ou remover o SynthID do vídeo. Antes do primeiro uso automatizado com créditos reais, confirmar as condições de uso e instruções automatizáveis vigentes do Google para esse fluxo. Caso a automação não seja permitida ou deixe de funcionar, o mesmo contrato aceita um MP4 exportado manualmente do Flow. A Gemini API é um motor futuro distinto, com faturamento próprio.
Fontes Google: criação, edição e sequência, download, créditos, termos gerais, Gemini API.