# Publicação automática — plano e contratos (17/11/2026) Documento-fonte para quem implementa. Pesquisa das plataformas: [PESQUISA.md](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 = "--"` (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": "" }` 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" | ```ts 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/ --remote-debugging-port= --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) = `":"`. 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).