Skip to content

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 ​

LocalComportamento atualMudança planejada
atpares-api/apps/api/src/modules/publications/publications.service.tsshort_video chama runVideo e RemotionDesviar apenas flow_web para um job durável; evitar geração duplicada
atpares-api/apps/api/src/modules/publications/publications.controller.tsPOST :id/video inicia Remotion; GET :id/video lê MP4Expor escolha do motor, estado, candidato e aprovação
atpares-api/apps/api/src/modules/publications/publications.repository.tsvideo e videoKey guardam o ativo finalManter essas colunas; acrescentar origem e job/candidato separados
atpares-api/apps/api/src/modules/integrations/media-publisher.service.tsLê videoKey para publicar ReelReutilizar sem mudar a publicação nas redes
atpares-app/src/modules/projects/components/CoverCard.vueBotão gera vídeo com RemotionMostrar origem, início, progresso, prévia e aprovação do Flow
atpares-infra/docker-compose.atpares.ymlAPI e Redis na rede privada atparesAdicionar 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| UI

O 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 ​

  1. 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 como queued antes do envio.
  2. O dispatcher envia um job idempotente ao serviço. Se o envio falhar, o job continua em queued e pode ser reenviado após reinício.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. A UI apresenta o candidato, custo observado quando disponível e checklist editorial. Só a aprovação humana promove o MP4 para videoKey, atualiza video para 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:

CampoUso
id, project_id, publication_id, owner_idEscopo e autorização da API
engine, state, attempt, idempotency_keyExecução e retomada
briefing_json, briefing_hashSnapshot imutável; sem senha ou cookie
flow_project_ref, flow_scene_refRetomada best effort; dados opacos da UI
candidate_key, sha256, media_metadata_jsonArquivo de revisão e prova de integridade
credit_budget, credit_usage_observedTeto por job e prestação de contas
error_code, error_summary, created_at, updated_at, lease_untilRecuperaçã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_EMAIL e FLOW_GOOGLE_PASSWORD ficam no .env. Porta 4320, API interna http://atpares-api:4310, perfil /data/browser-profile, artefatos /data/artifacts, concorrência 1 e 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 queued ou needs_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.