Files
MateuusandClaude Opus 5.5 84f30bbc2d CenaForge: primeira versão pública
Gerador de vídeos narrativos (Godot + FFmpeg), painel Next.js, serviço de voz,
Clipador de lives e Publicador para YouTube, TikTok e Instagram.

Inclui a leitura das visualizações dos posts para o Dashboard e o botão
"Publicar no <rede>" nos cartões das publicações.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 16:35:09 -03:00

20 KiB
Raw Permalink Blame History

Publicação automática — plano e contratos (17/11/2026)

Documento-fonte para quem implementa. Pesquisa das plataformas: PESQUISA.md. Identificadores de código em inglês; textos de UI, comentários e mensagens em português.

1. O que o usuário pediu

  • Canal de publicação: agrupa perfis de YouTube, TikTok e Instagram. É a entidade que hoje se chama "Conta" no painel (tabela accounts). Na UI passa a se chamar "Canal de publicação". No Clipador, os streamers de onde saem os cortes passam a se chamar "Fontes" na UI (o código e as rotas continuam channels).
  • Um canal de publicação é ligado a histórias e a fontes do Clipador (vínculos já existem: account_stories, account_channels).
  • Quando um vídeo é aprovado ele é publicado nas redes do canal. Cada canal tem aprovação automática (liga/desliga) e quando publicar: "na hora" ou "próximo horário bom", com limite de vídeos por dia por rede.
  • Dois modos de conexão em cada rede, escolhidos pelo usuário perfil a perfil (sem padrão imposto):
    • API oficial (OAuth / token).
    • Sessão logada (sem API): o usuário faz login à mão num Chrome/Edge normal; a sessão fica salva e o sistema publica pelo site usando essa sessão.
  • Nova aba Configurações no painel.
  • Design acessível e fácil de entender (requisito explícito).

2. Arquitetura

 navegador ──► Painel Next (4500) ──────────────► Publicador Python (4530) ──► YouTube / TikTok / Instagram
               cérebro: canais, regras,            executor: cofre de tokens,     (API oficial  OU
               fila de publicação, despachante     OAuth, perfis de navegador,     navegador via CDP 4540–4549)
               (laço em instrumentation.ts)        jobs de envio com progresso
                     │
                     └──► Clipador (4520): lê cortes ready/approved, aprova (PATCH) e marca published
  • Painel = cérebro. Dono da verdade: canais, configurações, fila (publish_jobs). Um laço único (panel/src/instrumentation.ts, protegido por globalThis contra duplicação no HMR) roda a cada 20 s. O painel precisa estar aberto para publicar/agendar — a UI diz isso.
  • Publicador = executor (publisher/, Python FastAPI, porta 4530, chave X-Service-Key como o Clipador). Não sabe o que é canal/história/corte: recebe um job com arquivo + metadados + perfil e devolve progresso/resultado. Guarda os segredos (cofre DPAPI) e os perfis de navegador. Jobs persistem no SQLite dele; um worker por vez.
  • Perfil = (canal, rede). profileId = "<accountId>--<platform>" (ex.: historias-do-litoral--youtube).

Regras de segurança e honestidade (valem para todos)

  • Modo sessão: navegador visível, o usuário loga à mão (2FA normal). Proibido: automatizar senha, resolver captcha, "stealth"/burla de detecção, patchright, stealth.js. Um envio por vez, ritmo humano. Login pedido / captcha / checkpoint ⇒ job para em needs_login e o usuário é avisado. Não tentar contornar.
  • O modo sessão viola os termos das três redes (risco de bloqueio da conta): a UI mostra esse aviso antes de conectar e pede confirmação explícita.
  • Segredos nunca voltam para o navegador (a API diz só configured: true/false). Tokens no cofre DPAPI (CryptProtectData, escopo do usuário Windows) em data/publisher/.
  • Nunca dizer "publicado" sem URL/ID remoto confirmado. Com aprovação automática desligada nada sai sem aprovação humana.

3. Publicador (publisher/, porta 4530) — contrato HTTP

Todas as rotas exigem X-Service-Key, exceto GET /health e GET /oauth/callback/{platform} (validada por state). Erros: { "detail": "<mensagem em pt-BR>" } com 4xx/5xx. Campos JSON em camelCase.

Método e rota Corpo → Resposta
GET /health { ok: true }
GET /v1/status { browser: { found: bool, kind: "chrome"|"msedge"|null, path }, worker: "idle"|"busy", queue: int }
GET /v1/apps { youtube: AppState, tiktok: AppState, instagram: AppState } — AppState = { configured: bool, clientId: string|null, redirectUri: string, notes: string } (sem segredo)
PUT /v1/apps/{platform} { clientId, clientSecret } → AppState
DELETE /v1/apps/{platform} → AppState
GET /v1/profiles/{profileId} → Profile
POST /v1/profiles/{profileId}/connect { platform, mode: "official"|"session" } → { profile: Profile, next: Next }
POST /v1/profiles/{profileId}/token { accessToken } (Instagram oficial: token colado) → Profile
POST /v1/profiles/{profileId}/session/check confere a sessão (abre a página de upload e verifica login) → Profile
POST /v1/profiles/{profileId}/session/open reabre a janela para o usuário relogar → { profile, next }
DELETE /v1/profiles/{profileId} desconecta: apaga tokens e o diretório do perfil de navegador → Profile
GET /v1/profiles/{profileId}/tiktok/creator-info (TikTok oficial) → { nickname, privacyOptions: string[], maxDurationS, commentDisabled, duetDisabled, stitchDisabled }
POST /v1/jobs JobInput → Job (201)
GET /v1/jobs/{jobId} → Job
POST /v1/jobs/{jobId}/cancel → Job (só se ainda queued)
GET /oauth/callback/{platform} troca code por token; devolve HTML simples "Conectado, pode fechar esta aba"
type Profile = {
  profileId: string; platform: "youtube" | "tiktok" | "instagram";
  mode: "official" | "session" | null;
  status: "disconnected" | "connecting" | "connected" | "needs_login" | "expired" | "error";
  displayName: string | null; handle: string | null;      // lidos da rede quando possível
  connectedAt: string | null; expiresAt: string | null;   // ISO; expiresAt = validade do refresh/token longo
  lastCheckAt: string | null; lastError: string | null;
};
type Next =
  | { kind: "open_url"; url: string }            // painel abre em nova aba (OAuth YouTube/TikTok)
  | { kind: "paste_token"; help: string }        // Instagram oficial
  | { kind: "browser_opened"; help: string }     // modo sessão: janela aberta, usuário loga e clica "Já entrei"
  | { kind: "none" };
type JobInput = {
  profileId: string; platform: "youtube" | "tiktok" | "instagram";
  file: string;            // caminho ABSOLUTO do MP4 (dentro da raiz do projeto — o serviço confere)
  cover: string | null;    // caminho absoluto de JPG/PNG ou null
  title: string;           // YouTube: título (≤100); TikTok/Instagram: ignorado (usam caption)
  caption: string;         // descrição / legenda com hashtags (≤2200)
  tags: string[];
  privacy: "public" | "unlisted" | "private";   // TikTok: public→PUBLIC_TO_EVERYONE, private→SELF_ONLY
  publishAt: string | null;                    // só YouTube oficial (agendamento nativo); demais ignoram
  aiGenerated: boolean;                        // containsSyntheticMedia / is_aigc / is_ai_generated
  madeForKids: boolean;                        // YouTube
  tiktokMode: "direct" | "draft";              // TikTok oficial: direct = Direct Post; draft = inbox
};
type Job = {
  jobId: string; profileId: string; platform: string;
  status: "queued" | "running" | "done" | "failed" | "needs_login" | "canceled";
  step: string;            // texto curto em pt-BR para a UI ("Enviando vídeo…", "Aguardando processamento…")
  progress: number;        // 0..1
  remoteId: string | null; url: string | null;
  draft: boolean;          // true = foi para rascunho/inbox (TikTok draft), não está público
  error: string | null; createdAt: string; updatedAt: string;
};

Implementação por rede

Rede Oficial Sessão logada
YouTube Cliente OAuth "Desktop app", PKCE, redirect http://127.0.0.1:4530/oauth/callback/youtube, escopo youtube.upload (+youtube.readonly p/ nome do canal). videos.insert resumable; status.containsSyntheticMedia, selfDeclaredMadeForKids, publishAt (com private). Capa via thumbnails.set depois do processamento. Refresh token. studio.youtube.com → Criar → Enviar vídeos
TikTok Login Kit desktop, PKCE S256 com desafio em hex, redirect http://127.0.0.1:4530/oauth/callback/tiktok, escopos user.info.basic,video.upload,video.publish. creator_info/query antes; FILE_UPLOAD em blocos (5–64 MB). draft → /v2/post/publish/inbox/video/init/. Access 2 h; refresh 180 d rotativo (gravar o novo sempre). Sem auditoria: Direct Post só SELF_ONLY — o serviço devolve isso no step/erro de forma clara. tiktok.com/tiktokstudio/upload
Instagram Token colado (gerado no painel de desenvolvedor da Meta — Instagram API with Instagram Login; a Meta não aceita redirect localhost). Container media_type=REELS → upload resumable rupload com o arquivo local (testar com graph.instagram.com; se a rede recusar, erro claro dizendo que é preciso Facebook Login for Business) → polling status_code → media_publish. Token longo 60 d, renovar com refresh_access_token quando faltar < 10 d. instagram.com → Criar → Reel

Modo sessão (comum às três): localizar Chrome (preferido) ou Edge instalado; abrir como processo normal com --user-data-dir=data/publisher/browser/<profileId> --remote-debugging-port=<livre em 4540–4549> --no-first-run; conectar com Playwright Python connect_over_cdp (só o driver; não baixa navegador). Seletores por role/label/texto (PT e EN), screenshot em data/publisher/logs/ quando falhar. Sessão expirada = página de login, botão "Entrar/Log in" ou ausência do campo de arquivo ⇒ needs_login. Um job por vez. Depois de publicar, ler a URL do vídeo se a tela mostrar; se não, remoteId = null, url = null e step explica ("publicado; link não encontrado na tela").

Infra: publisher/.env (PUBLISHER_SERVICE_KEY, PUBLISHER_PORT=4530), publisher/.env.example, .venv, requirements.txt com versões fixas, pytest com chamadas de rede simuladas. Entra em scripts/dev.ts (depois do Clipador, pula com aviso se faltar .venv/chave), scripts/setup.ps1 (venv + chave) e package.json (test:publisher). Dados em data/publisher/ (publisher.db, vault, browser/, logs/).

4. Painel — dados (migração v5 em panel/src/lib/db.ts)

  • account_networks: o status deixa de ser 'mock' → 'disconnected'|'connecting'|'connected'|'needs_login'|'expired'|'error' (migrar mock → disconnected); novas colunas mode TEXT NULL ('official'|'session'), enabled INTEGER DEFAULT 1, daily_limit INTEGER DEFAULT 3, privacy TEXT DEFAULT 'public', tiktok_mode TEXT DEFAULT 'direct', display_name TEXT, last_error TEXT, checked_at TEXT. handle passa a aceitar NULL até a rede informar.
  • accounts: approval_mode TEXT DEFAULT 'manual' ('manual'|'auto'), timing TEXT DEFAULT 'best_slot' ('now'|'best_slot'), ai_label TEXT DEFAULT 'auto' ('auto'|'always'|'never').
  • publish_jobs: id, account_id, platform, source_kind ('clip'|'episode'), source_id TEXT, file, cover, title, caption, status ('awaiting_approval'|'scheduled'|'queued'|'publishing'|'published'|'failed'|'needs_login'|'canceled'), scheduled_at, publisher_job_id, step, progress, remote_id, url, draft, error, attempts, created_at, updated_at, UNIQUE(account_id, platform, source_kind, source_id).
  • publications: episode_id passa a NULL-ável, nova coluna clip_id INTEGER, job_id. Registro real (simulated=0) ao publicar.
  • episodes: approved_at TEXT, approved_render_id INTEGER, publish_title TEXT, publish_caption TEXT.
  • app_settings(key PRIMARY KEY, value): publishing_paused (0/1), slots (JSON por rede, horário de Brasília — padrão: youtube 12:00/15:00/19:00, tiktok 08:00/12:00/19:00/21:00, instagram 12:00/19:00/21:00), timezone.

5. Painel — despachante (laço de 20 s)

  1. Cortes: busca no Clipador os cortes ready e approved das fontes ligadas a canais ativos.
    • ready + canal com approval_mode=auto ⇒ aprova no Clipador (PATCH status=approved) e cria jobs.
    • ready + canal manual ⇒ cria job awaiting_approval (aparece em "Aguardando aprovação").
    • approved (por humano) ⇒ jobs awaiting_approval desse corte viram agendados/na fila.
    • Corte que voltou para pending (editado/exportado) ou foi rejeitado/apagado ⇒ cancela jobs ainda não enviados.
  2. Episódios: botão "Aprovar para publicar" (exige render final) cria os jobs; com canal auto, aprovar o render final já cria os jobs aprovados.
  3. Agendar: timing=now ⇒ queued. best_slot ⇒ próximo horário livre da rede em slots, respeitando daily_limit (conta publicados + agendados no dia) e espaçando ≥ 1 h na mesma rede/canal. YouTube oficial pode usar publishAt.
  4. Enviar: jobs queued (ou scheduled vencido) com perfil connected/enabled e sem publishing_paused ⇒ POST /v1/jobs no Publicador; acompanha GET /v1/jobs/{id} até terminar; grava step/progress.
  5. Terminar: done ⇒ published, grava publications (real) e, se todos os jobs do corte terminaram, marca o corte published no Clipador. needs_login ⇒ perfil needs_login. failed ⇒ failed com erro e botão "Tentar de novo".
  6. Legenda: corte = title/caption do Clipador (crédito já vem no fim). Episódio = publish_title/publish_caption. aiGenerated: always/never pelo canal; auto = true só se o episódio usa voz RVC de personagem/voz clonada.

API do painel (rotas novas; padrão errorResponse)

  • GET/PUT /api/settings — { publishingPaused, slots, timezone }.
  • GET/PUT/DELETE /api/settings/apps/[platform] — repassa ao Publicador (sem segredo na resposta).
  • GET /api/publisher/status — saúde do Publicador + navegador encontrado.
  • PATCH /api/accounts/[id] — aceita também approvalMode, timing, aiLabel.
  • PUT /api/accounts/[id]/networks/[platform] — { enabled?, dailyLimit?, privacy?, tiktokMode? }.
  • POST /api/accounts/[id]/networks/[platform]/connect { mode } → { network, next }; .../token { accessToken }; .../check; .../reopen; DELETE .../networks/[platform] desconecta.
  • GET /api/publishing/jobs?status=&accountId= → lista; POST /api/publishing/jobs/[id]/(approve|publish-now|retry|cancel); PATCH /api/publishing/jobs/[id] { scheduledAt?, title?, caption? }.
  • POST /api/episodes/[id]/approve { renderId, title, caption }; DELETE desfaz.
  • GET /api/publishing/summary — contagens por status (para o menu e o dashboard).

6. Painel — telas (acessíveis)

  • Menu: Distribuição → "Canais de publicação" (rota /accounts) e "Publicações" (/publishing, com contador de "aguardando aprovação"); rodapé → "Configurações" (/settings).
  • Canais de publicação: cartão por canal com as três redes. Cada rede mostra estado em palavras e ícone (nunca só cor): "Não conectado", "Conectado como @x", "Precisa entrar de novo", "Erro: …". Botão Conectar abre um passo a passo: 1) escolher o modo — dois cartões lado a lado, "Conta oficial (API)" vs "Sessão logada", com prós, contras e o aviso de termos; 2) instruções do modo (abrir login / colar token / "Já entrei"); 3) conferência. Configurações do canal em linguagem simples: "Aprovar sozinho os vídeos novos?" (Switch), "Quando publicar?" (Na hora / No próximo horário bom), "Máximo por dia" por rede, privacidade, rótulo de IA.
  • Publicações: abas "Aguardando aprovação", "Agendadas", "Publicando", "Publicadas", "Com problema". Cada item: capa, título, canal, rede, horário, estado em texto, progresso; ações: Aprovar, Publicar agora, Mudar horário, Cancelar, Tentar de novo, Entrar de novo. Aviso fixo se o Publicador estiver desligado ou "publicação pausada".
  • Configurações: abas "Publicação" (pausar tudo, horários bons por rede, fuso), "Apps das redes" (passo a passo para criar o app de cada rede, campos de Client ID/Secret, redirect pronto para copiar, estado configurado/não), "Navegador" (navegador encontrado, onde ficam as sessões, aviso de termos) e "Sobre os modos".
  • Clipador: "Canais" → "Fontes" nos textos; aba Aprovados mostra o estado da publicação por rede.
  • Histórias/episódio: botão "Aprovar para publicar" com prévia do vídeo final, título e legenda editáveis e os canais que vão receber.
  • Acessibilidade: WCAG 2.2 AA — contraste ≥ 4,5:1, foco visível, tudo por teclado, aria-live para progresso e resultados, rótulos em todos os campos, alvos ≥ 24 px, texto simples (sem jargão; "API"/"OAuth" só com explicação).

7. Divisão do trabalho

Parte Quem Arquivos (dono exclusivo)
A — Publicador agente geral publisher/**, scripts/dev.ts, scripts/setup.ps1, package.json (raiz), start.bat
B — Painel back-end agente geral panel/src/lib/**, panel/src/app/api/**, panel/src/instrumentation.ts, clipper/** (só se faltar algo)
C — Painel UI cenaforge-dashboard-designer panel/src/app/**/page.tsx e layouts, panel/src/components/**
D — Revisão + skill revisores + cenaforge-skill-updater só leitura / skill

Regras: o painel (pnpm panel) é do usuário — não iniciar, não encerrar, não rodar next build; use pnpm --filter cenaforge-panel typecheck. Next.js 16 tem mudanças incompatíveis: ler panel/node_modules/next/dist/docs/ antes. Portas só 4500–4599.

7b. Ajustes depois da revisão (17/11/2026)

  • Migração v6 do painel: publish_jobs.schedule_source (agendamento automático × manual) e cancel_reason = 'unlinked'.
  • Idempotência: JobInput.clientRef (≤ 80) = "<publish_jobs.id>:<attempts>". O Publicador guarda UNIQUE e, com clientRef repetido, devolve 200 com o job existente (201 = novo). attempts só sobe em retry explícito.
  • PublishJob.mayBeLive: retry exige { confirm: true } (409 sem) — conferir na rede antes de reenviar.
  • Agendamento automático vencido há > 30 min é reencaixado; encerrar fonte/história cancela jobs não enviados.
  • Publicador aceita file/cover só de output/, stories/, assets/.
  • API do painel protegida por panel/src/proxy.ts: Host local; métodos de escrita exigem Origin do mesmo host e Content-Type: application/json. Script/curl: mande -H "Origin: http://127.0.0.1:4500" -H "Content-Type: application/json".

7c. "Publicar" no cartão do corte (17/11/2026)

  • Corte aprovado (ou já publicado) no Clipador ganha o botão Publicar (aba Aprovados). O diálogo pede o canal de publicação, as redes (só as conectadas e ligadas; as que já têm o corte publicado, na fila ou em envio ficam desmarcadas com o motivo) e quando sai (agora ou no próximo horário bom). Título e legenda são os do cartão.
  • POST /api/publishing/clips/[id] {accountId, platforms[], timing?: "now"|"best_slot"} → {jobs, skipped[{platform, reason}], placed}. O clique é a aprovação humana. "Agora" ignora horário bom e limite do dia (como "Publicar agora").
  • Não precisa ligar a fonte ao canal. Banco v7: publish_jobs.origin = link (despachante, pelo vínculo) | manual (este botão). Job manual não é cancelado por "fonte desligada" (planClipSync, linkActive, endChannel); continua cancelado se o corte for editado, rejeitado ou apagado.

8. Pronto quando

  • Publicador sobe pelo pnpm dev, pytest verde, typecheck do painel e da raiz verdes.
  • Conectar cada rede nos dois modos pela UI (fluxo completo até "Conectado" ou erro claro).
  • Corte aprovado (manual e automático) vira job, respeita horário/limite, sai e grava publications real.
  • Episódio aprovado idem.
  • Teste real de envio em pelo menos uma rede com conta do usuário (depende das credenciais dele).