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>
20 KiB
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 continuamchannels). - 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 porglobalThiscontra 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, chaveX-Service-Keycomo 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_logine 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) emdata/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 |
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: ostatusdeixa de ser'mock'→'disconnected'|'connecting'|'connected'|'needs_login'|'expired'|'error'(migrarmock→disconnected); novas colunasmode 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.handlepassa 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_idpassa a NULL-ável, nova colunaclip_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)
- Cortes: busca no Clipador os cortes
readyeapproveddas fontes ligadas a canais ativos.ready+ canal comapproval_mode=auto⇒ aprova no Clipador (PATCH status=approved) e cria jobs.ready+ canal manual ⇒ cria jobawaiting_approval(aparece em "Aguardando aprovação").approved(por humano) ⇒ jobsawaiting_approvaldesse corte viram agendados/na fila.- Corte que voltou para
pending(editado/exportado) ou foi rejeitado/apagado ⇒ cancela jobs ainda não enviados.
- 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. - Agendar:
timing=now⇒queued.best_slot⇒ próximo horário livre da rede emslots, respeitandodaily_limit(conta publicados + agendados no dia) e espaçando ≥ 1 h na mesma rede/canal. YouTube oficial pode usarpublishAt. - Enviar: jobs
queued(ouscheduledvencido) com perfilconnected/enablede sempublishing_paused⇒POST /v1/jobsno Publicador; acompanhaGET /v1/jobs/{id}até terminar; gravastep/progress. - Terminar:
done⇒published, gravapublications(real) e, se todos os jobs do corte terminaram, marca o cortepublishedno Clipador.needs_login⇒ perfilneeds_login.failed⇒failedcom erro e botão "Tentar de novo". - Legenda: corte =
title/captiondo Clipador (crédito já vem no fim). Episódio =publish_title/publish_caption.aiGenerated:always/neverpelo 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émapprovalMode,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 };DELETEdesfaz.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-livepara 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) ecancel_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).attemptssó 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/coversó deoutput/,stories/,assets/. - API do painel protegida por
panel/src/proxy.ts: Host local; métodos de escrita exigemOrigindo mesmo host eContent-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,pytestverde, 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
publicationsreal. - Episódio aprovado idem.
- Teste real de envio em pelo menos uma rede com conta do usuário (depende das credenciais dele).