# Publicação em YouTube, TikTok e Instagram (Publicador + despachante do painel) Fonte completa: `doc/publicacao/PLANO.md` (contrato HTTP do Publicador §3, banco §4, despachante §5, telas §6) e `doc/publicacao/PESQUISA.md` (fatos das plataformas, datados de 17/11/2026, reverificar a cada 3 meses). Instalação, apps das redes e regras do modo sessão: `publisher/README.md`. Aqui só o que um agente precisa para agir. ## Quem faz o quê ``` Painel (4500) = cérebro ──► Publicador (4530) = executor ──► YouTube / TikTok / Instagram canais, regras, fila cofre DPAPI, OAuth, perfis de API oficial OU Chrome/Edge via CDP (4540–4549) publish_jobs, laço 20 s navegador, jobs (um por vez) └──► Clipador (4520): lê cortes ready/approved (GET /v1/clips?channel=&status=&ids=), aprova e marca published ``` - **Despachante**: `panel/src/instrumentation.ts` → `startDispatcher` (`lib/dispatcher.ts`, `TICK_INTERVAL_MS` 20 s, guarda em `globalThis` contra laço duplo no HMR) → `dispatcherTick` (`lib/publishing.ts`, que ao carregar troca `dispatcherState().tick` pela versão nova: sem isso o laço usa as regras antigas, gotchas 141). **Só publica com o `pnpm panel` aberto** (o painel é do usuário: não inicie nem encerre). - **Publicador** (`publisher/`, Python 3.12 FastAPI): não conhece canal, história nem corte; recebe arquivo + metadados + `profileId` (`--`). Toda rota exige `X-Service-Key` (`PUBLISHER_SERVICE_KEY` em `publisher/.env`), exceto `GET /health` e `GET /oauth/callback/{platform}` (validada por `state`). Dados em `data/publisher/` (`publisher.db`, `vault.bin` DPAPI, `browser//`, `logs/` com capturas das falhas). - Subir: `pnpm dev` (sobe depois do Clipador; sem `publisher/.venv` ou chave, pula com aviso). Instalar: `setup.bat` (passo 6b2 do `scripts/setup.ps1`). Testes: `pnpm test:publisher` (pytest, sem rede nem navegador) e `pnpm --filter cenaforge-panel test:panel` (node:test via tsx em `panel/src/lib/*.test.ts`, banco temporário por `CENAFORGE_ROOT`). Typecheck do painel: `pnpm --filter cenaforge-panel typecheck`. ## Onde mexer | Mudança | Arquivo(s) | |---|---| | Contrato HTTP, fila, cofre, OAuth | `publisher/app/` (`main.py` rotas, `service.py` regras, `worker.py` fila, `vault.py`, `db.py` (v2: `jobs.client_ref` UNIQUE), `paths.py` (`file`/`cover` só de `output/`, `stories/`, `assets/`; `data/` recusado), `acl.py` (ACL de `data/publisher` só para o usuário), `config.py`) | | API oficial de uma rede | `publisher/app/platforms/{youtube,tiktok,instagram}_api.py` | | Modo sessão (navegador) | `publisher/app/platforms/session/` (`browser.py` abre Chrome/Edge normal com `--user-data-dir` e `--remote-debugging-port`, confere a porta pelo `DevToolsActivePort` do perfil ou, se o Chrome 157+ não o gravar (porta fixa), pela marca `CenaForgeWindow.json` + PID que escuta (`owns_port`, `listener_pid`; gotchas 137), fecha a janela (`IDLE_CLOSE_S`/`LOGIN_IDLE_CLOSE_S`); `runner.py` (`_with_page` conecta com `connect_over_cdp(..., is_local=True)`: sem isso arquivo > 50 MB é recusado, gotchas 139; `browser_error_text(detail)` traduz o `PlaywrightError` em frase específica (clique com timeout, timeout, arquivo > 50 MB, janela fechada) ou, no resto, "O navegador travou ou mudou de página"; o "Detalhe" técnico vem depois); `common.py`: `step_pause`, `fill_text`, `click_through`, `dismiss_tips`, `TIP_BUTTONS`, `screenshot`, `prune_screenshots`); seletores no dicionário `SELECTORS` de `youtube_studio.py`, `tiktok_studio.py`, `instagram_web.py` | | Cliente do Publicador no painel | `panel/src/lib/publisher.ts` | | Regras puras (horário bom, limite, ações do job, sincronização de cortes, leitura do resultado, reencaixe, idempotência) | `panel/src/lib/publishing-rules.ts` (`placeJob`, `nextFreeSlot`, `planClipSync`, `readPublisherJob`, `jobActions`, `aiGeneratedFor`, `tagsFromCaption`, `needsReflow`/`STALE_AFTER_MS`, `clientRefFor`, `mayBeLive`, `parseVideoUrl`) + `publishing-rules.test.ts` | | Fila, aprovação, envio, episódio | `panel/src/lib/publishing.ts` (`approveJob`, `placeApproved`, `retryJob`, `sendDue`, `promoteDue`, `pollPublishing`, `finishFromPublisher`, `markPublished`) + `publishing-db.test.ts` | | Pausar tudo, horários bons, fuso | `panel/src/lib/settings.ts` (tabela `app_settings`) | | Banco | `panel/src/lib/db.ts`: **v5** (`account_networks` reconstruída sem `mock`, `publish_jobs`, `publications` com `clip_id`/`job_id`, `app_settings`, `clip_auto_approvals`, colunas novas em `accounts` e `episodes`), **v6** (`publish_jobs` reconstruída: `schedule_source` `auto`/`manual`/`now`, `cancel_reason` aceita `unlinked`), **v7** (`publish_jobs.origin` `link`/`manual`, padrão `link`) e **v8** (`metric_syncs`) | | "Publicar" no cartão do corte (sem fonte ligada) | UI `panel/src/components/clip-publish.tsx` (`ClipPublishButton` + diálogo; usado em `clipper-queue.tsx`, em `approved` e, como "Publicar em outra rede", em `published`; `useClipPublishing().reload()`); cliente `publishClip` em `publishing-client.ts`; rota `POST /api/publishing/clips/[id]` (`app/api/publishing/clips/[id]/route.ts`); servidor `publishClip` em `publishing.ts` | | Guarda da API do painel | `panel/src/proxy.ts` (Next 16: o middleware se chama `proxy`; `checkRequest` exportado) + `proxy.test.ts`; `readJson` em `panel/src/lib/http.ts` (415 sem JSON) | | Rotas | `/api/settings` e `/api/settings/apps/[platform]`, `/api/publisher/status`, `/api/publishing/jobs[/[id][/[action]]]`, `/api/publishing/summary`, `/api/episodes/[id]/approve`, `/api/accounts/[id]/networks/[platform]/(connect|token|check|reopen|creator-info)` | | Telas | `/accounts` "Canais de publicação" (`account-manager.tsx`, `account-networks.tsx`, `connect-wizard.tsx`), `/publishing` "Publicações" (`publishing-board.tsx`, `publishing-client.ts`), `/settings` "Configurações" (`settings-panel.tsx`) | | Modal novo (qualquer tela) | `Dialog` + `Steps` de `panel/src/components/dialog.tsx` (`` nativo, foco preso, Esc fecha). Confirmação simples continua em `askConfirm` (panel.md) | | Avisos e chips de estado por rede | `NoticeBar` e `PublishChips` em `panel/src/components/publishing-ui.tsx` | Botões de um job vêm de `actions[]` da API (`jobActions` no servidor); a UI não decide sozinha o que oferecer. No texto visível do Clipador "Canais" virou **"Fontes"**; código, tabelas e rotas continuam `channels`. ## Regras que não podem quebrar - **Nunca `published` sem ID/URL remota** (ou rascunho confirmado). `done` sem link ⇒ `failed` com aviso para conferir na rede antes de "Tentar de novo" (evita publicar duas vezes). Publicador fechado no meio de um envio ⇒ `failed` "interrompido — tente de novo": também conferir na rede. - **Aprovar vale para o vídeo inteiro** (todas as redes e canais daquela origem); tirar uma rede = cancelar o job dela. - **Aprovação automática** (`accounts.approval_mode = 'auto'`) só pega cortes criados depois de ligá-la (`accounts.auto_since`) **e** depois de a fonte ser ligada ao canal. Episódio **sempre** precisa do clique "Aprovar para publicar" (exige render final). - "Na hora" (`timing = 'now'`) respeita o limite diário (`account_networks.daily_limit`); passou do limite, agenda no próximo horário bom. - `publishAt` nativo do YouTube **não é usado** (o painel manda `null`); o agendamento é do despachante. - **Modo sessão viola os termos das três redes**: a UI exige marcar "Entendi o risco". Proibido stealth/patchright/ stealth.js, resolver captcha ou digitar senha; login, captcha ou checkpoint ⇒ `needs_login` e o usuário resolve. Não rode `playwright install` (só o driver; o navegador é o Chrome/Edge do usuário). - Segredos nunca voltam ao navegador (só `configured: true/false`) e nunca vão para logs nem para esta skill. - **Idempotência:** o painel manda `clientRef = ":"`; o Publicador devolve **200** com o job existente (201 = novo). `attempts` só sobe em "Tentar de novo"/reaprovação. Timeout, conexão caída, 5xx ou 401/403/404 ao criar ⇒ o job **fica na fila** e reenvia com o mesmo `clientRef`; outro 4xx ⇒ `failed`. - **`mayBeLive`** (falhou depois de chegar ao Publicador): `POST /api/publishing/jobs//retry` sem `{confirm: true}` ⇒ 409; a UI pergunta "Confira na rede se o vídeo já saiu". Agente não manda `confirm: true` sem o usuário ter conferido. - Agendamento automático vencido há > 30 min (painel fechado) é reencaixado no próximo horário bom; horário manual, "Publicar agora" e "Tentar de novo" saem como estão. - Encerrar fonte/história cancela os jobs não enviados (`unlinked`); religar zera `linked_at` (a automática não pega cortes do intervalo desligado). Cancelar no meio de um ciclo vale (UPDATEs condicionais; se o Publicador já criou o envio, o painel cancela lá). Aprovação automática é registrada em `clip_auto_approvals` antes do PATCH no Clipador. - **Só o vídeo FINAL sai** (18/11/2026): corte de fonte com camadas de teste (tradução, dublagem) tem um vídeo de revisão e, ao aprovar, um final sem elas. `clipPublishFile` (`publishing-rules.ts`) devolve `publishFile` ou o motivo de esperar; `sendDue` relê o corte e deixa o job em "Esperando o vídeo final…" até estar pronto; nunca use `file`. Detalhes: [clipper-video.md](clipper-video.md), gotchas 180. - **Botão "Publicar" do corte** (`POST /api/publishing/clips/`, corpo `{accountId, platforms[], timing?: "now"|"best_slot"}`, resposta `{jobs, skipped[{platform, reason}], placed}`; `publishClip`; `timing` também aceita `"at"`, ver abaixo): serve para corte aprovado cuja fonte **não** está ligada a canal (`account_channels`) ou para outra rede. O clique é a aprovação humana. `timing` omitido = o do canal. `"now"` força `queued` com `schedule_source='now'` e ignora o limite do dia. Job existente cancelado, `failed` ou `needs_login` é reaproveitado (`attempts`+1 via `placeApproved`, que ganhou `opts.timing`); rede não conectada, pausada, já publicada, na fila, agendada, enviando ou "pode ter saído" (`mayBeLive`) entra em `skipped` com motivo. O diálogo lista essas redes bloqueadas com o motivo. Título e legenda são os do cartão. - **"Horário específico"** no diálogo do corte: `timing: "at"` + `scheduledAt: { youtube?, tiktok?, instagram? }` (ISO, um por rede escolhida, obrigatório para cada uma). `ClipTiming = PublishTiming | "at"` (`publishing.ts` e `publishing-client.ts`; o "quando sai" do canal continua `now|best_slot`). `readChosenTimes` ⇒ `UserError` em português para rede sem horário, horário passado (> 1 min) ou além de 1 ano. `placeApproved` com `preferredAt` (mínimo agora+5 s) ⇒ `scheduled`, `schedule_source 'manual'`, "Agendado por você."; ignora horário bom e limite do dia (como "now"). Rede já `scheduled`/`queued` sem `publisher_job_id` é reagendada. UI: terceira opção, `datetime-local` (sugestão: próxima hora cheia ≥ 30 min, horário do navegador); com mais de uma rede, "Horário diferente para cada rede". `toLocalInput()` agora é export de `publishing-client.ts`. Testes: 2 em `publishing-db.test.ts` ("horário específico: …"); painel 68/68 (informado, `npx tsx --test src/lib/*.test.ts`; não reexecutado). - **Capa do corte publicado** (gotchas 155): `clipCover()` copia a capa para `output/publishing/covers/clip-.` (`keepCover`); `keepClipCovers()` roda no início de `syncClips` e migra jobs antigos; `metrics.ts` só devolve capa que existe no disco. - **`publish_jobs.origin`**: `link` (criado pelo vínculo fonte↔canal) ou `manual` (botão "Publicar"). Job `manual` **não** é cancelado por "fonte desligada" (`planClipSync` com `ExistingJob.origin`, `linkActive`, `accounts.endChannel` só cancela `origin = 'link'`); corte editado, rejeitado ou apagado ainda cancela o job. Armadilha de migração: gotchas 138. - Rótulo de IA: se não der para ler a voz do episódio, vai ligado por cautela. **Corte (`source_kind = 'clip'`) nunca leva o rótulo**, nem com o canal em "always" (`sendDue`; gotchas 148). - **"Apaguei na rede"** (`removed`): `POST /api/publishing/jobs//removed`; `markRemoved` (`publishing.ts`) aceita só `published`, volta o job a `canceled`/`user`, zera url/remote_id/published_at e apaga a `publications` do job; `jobActions` de `published` = `["removed"]`; cliente `markJobRemoved`; botão em Publicadas com confirmação. O painel não apaga nada na rede (apague lá primeiro); depois "Publicar" no corte reenvia com `attempts`+1. Gotchas 149. - Modo sessão: a janela fecha depois de cada envio e do "Já entrei" (pede saída limpa, mata após 10 s); fica aberta se a rede pedir login/captcha; ociosa fecha em 5 min (15 min se aberta para login). Capturas só da área visível, nunca em login/captcha, apagadas após 7 dias. Ritmo: "intervalo mínimo entre envios" (30 s, `publisher/README.md`). - Segurança do Publicador: ACL de `publisher/.env` e `data/publisher/` restrita ao usuário (`setup.ps1` + `acl.py`); `code_verifier` do PKCE só em memória; loggers `httpx`/`httpcore` silenciados (o token do Instagram vai na URL). - **Link do vídeo no TikTok** (`find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` em `tiktok_studio.py`): a lista "Publicações" (`/tiktokstudio/content`) **não se atualiza sozinha** e o vídeo novo só entra depois de processar. Espera 5 s; a cada tentativa abre ou **recarrega** `CONTENT_URL` e lê 5 vezes (a cada 3 s); até 12 cargas (~3 min), com progresso "Publicado. Esperando o vídeo aparecer na lista do Studio… (n de 12)". **Só aceita o link cuja linha (até 10 ancestrais do ``) contém `caption_key(caption)`** (primeiros 24 caracteres da legenda sem #hashtags e @menções): nunca devolve o link de outro vídeo. Sem achar, `PublishResult` sem link e step "Publicado no TikTok (Studio), mas o vídeo não apareceu na lista do Studio em ~3 min; link não encontrado" ⇒ job `failed` (regra "nunca `published` sem URL"). No painel, `readPublisherJob` (`publishing-rules.ts`) reconhece `done` sem link com step começando em "Publicado no " e diz "Saiu na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o link' (não use 'Tentar de novo')". Não há seletor `video_link` (links relativos). Gotchas 140 e 143. - **"Já saiu: informar o link"** (`mark-published`): `POST /api/publishing/jobs//mark-published` com `{url}` (`markPublished` em `publishing.ts`; `MarkPublishedDialog` em `publishing-board.tsx`; cliente `markJobPublished`; `PublishJobAction` ganhou `"mark-published"`). Aparece em job `failed` (sempre; botão principal se `mayBeLive`) e `needs_login` (só se `mayBeLive`). `parseVideoUrl(platform, url)` (`publishing-rules.ts`) valida e devolve `{url, remoteId}`: TikTok `/@conta/video/`; YouTube shorts, `watch?v=` ou `youtu.be`, normalizado para `/shorts/`; Instagram `reel(s)` ou `p`; outro formato ou rede ⇒ erro. Faz UPDATE condicional para `published` com url e remote_id, `recordPublication` (registro real) e `kickDispatcher` (marca o corte `published` no Clipador). Use só depois de conferir na rede que o vídeo está lá; o agente não inventa o link. - **Primeiro envio real (TikTok, modo sessão, 17/11/2026 13:35):** público, `https://www.tiktok.com/@vortplay/video/7709179978520284437` (informado; login, upload, legenda, privacidade e "Publicar" funcionaram com conta real). O job terminou `failed` por falta do link (gotchas 140) e foi marcado como publicado pela rota acima. Seletores do TikTok validados nesse envio; **YouTube e Instagram em modo sessão: só o ensaio sem publicar (próxima regra). YouTube: o vídeo saiu em envio real, mas o painel não confirmou (regra "YouTube Studio"); a confirmação nova não foi testada.** - **Instagram em modo sessão** (`publisher/app/platforms/session/instagram_web.py`; layout novo de 17/11/2026, barra lateral só de ícones). Fluxo: o botão é `` com `` e abre DIRETO o diálogo "Criar novo post" (sem submenu; `create_post` só para o layout antigo), com o `input[type=file]` dentro do diálogo. - `SELECTORS["create"]` aceita "Postar" (svg, link, botão); erro: "o botão Postar". - `next`, `share` e `reels_notice_ok` são CSS presos a `_DIALOG` (`div[role='dialog']`): no feed cada post tem um botão de ícone "Compartilhar" e o seletor global podia clicá-lo (teste `test_buttons_of_the_flow_are_searched_inside_the_dialog`). - Envio dividido: `prepare(page, spec, progress, sleep)` faz tudo até devolver o locator do Compartilhar **sem clicar**; `upload` chama `prepare`, clica e espera "compartilhado". Todo clique passa por `click_through`. - **Rótulo de IA**: `input type=checkbox role=switch` SEM nome acessível, direto no painel (não em "Configurações avançadas", que só abre como plano B do layout antigo). `find_ai_switch` casa a linha (`AI_ROW_TEXT`, até 6 ancestrais por `innerText`); `_is_on` lê `aria-checked`/`is_checked`; confere de novo depois do clique e, se não ligou, `PublishError` (não publica sem o rótulo). Sem clique forçado (gotchas 145). - **Formato "Original"** (`keep_original_shape(page, sleep)`, chamada em `prepare` antes dos "Avançar"): a etapa "Cortar" vem em 1:1 e cortaria o vídeo vertical (o 1º reel real saiu quadrado, gotchas 147). Clica em `svg[aria-label='Selecionar corte']`/'Select crop' no diálogo e escolhe "Original" (`SELECTORS["crop_toggle"]`, `["crop_original"]`; opções Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ⇒ `PublishError`, nunca publica cortado. - `close_suggestions(page, text)`: legenda terminando em `#tag`/`@menção` ganha um espaço no fim (Esc fecharia a caixa). - **Link do reel**: o endereço não muda após compartilhar. `find_reel_url(page, caption, sleep, attempts=6, per_load=3, progress)` acha o link do perfil (`_PROFILE_HREF_JS`: `//` com `textContent` "Perfil" ou foto do perfil no `alt`; a barra recolhida esconde o texto), abre `//reels/`, abre os 3 mais novos ainda não conferidos e aceita o primeiro cuja página contém `caption_key(caption)` (agora em `common.py`, também usada pelo TikTok); recarrega até 6 vezes, 20 s entre elas (~3 min). `MEDIA` aceita `//reel//`. Sem link ⇒ `PublishResult` sem URL ⇒ job `failed` ⇒ "Já saiu: informar o link". - **Ensaio sem publicar** (jeito seguro de validar seletores com conta real): rodar `prepare` com o navegador do perfil, conferir o resultado e descartar o rascunho ("Descartar"); nunca clicar em Compartilhar sem pedido do usuário. - Validado ao vivo (informado, 17/11/2026, ensaio com `ai_generated=True`): Postar, arquivo `clip-29.mp4`, Avançar ×2, legenda "…#teste" intacta, rótulo de IA LIGADO, Compartilhar achado e não clicado, rascunho descartado, 0 diálogos no fim. `_PROFILE_HREF_JS` voltou `/vortplay27/`. **Não validados com conta real:** clique em Compartilhar, a confirmação "compartilhado" e `find_reel_url` (a conta ainda não tinha reels). Só vale depois de reiniciar o `pnpm dev`. - **Avisos de novidade do site (modo sessão):** o TikTok Studio abre avisos por cima da página ("Veja a prévia do seu vídeo no seu celular" → **Entendi**) que bloqueiam cliques. Todo clique do `tiktok_studio.py` passa por `click_through` (timeout 8 s; se falhar, `dismiss_tips` fecha os avisos e tenta de novo; sem aviso, relança o erro) e `dismiss_tips` roda antes da legenda e antes de "Publicar". `TIP_BUTTONS` só aceita `^(Entendi|Entendido|Ok, entendi|Got it)$`: **nunca aceitar ou recusar opções por esse caminho**, só fechar avisos. Gotchas 142. - **Legenda do TikTok com hashtags de verdade** (`tiktok_studio.py`: `caption_parts`, `type_caption`, `hashtag_options`): texto colado; cada `#tag` digitada e confirmada clicando na sugestão exata; sem sugestão fica texto; progresso "N de M hashtags confirmadas". Corrigido em 17/11/2026 após diagnóstico (`doc/publicacao/TIKTOK_DIAGNOSTICO.md`); **falta validar com vídeo real** (conferir `challenges`/`textExtra` na página pública). Gotchas 158–159. - **YouTube Studio (modo sessão): confirmar a publicação** (`youtube_studio.py`; gotchas 151). O `#done-button` é um componente `ytcp-button`, não um `