Files
MateuusandClaude Opus 5.5 b11090ffa3 Skill cenaforge 1.54.0: Clipador (revisão × final, dublagem, falantes, expressões, Equipe de IA)
Dois arquivos novos em references/ (clipper-video.md, clipper-ai-team.md), banco em v17,
seção de expressões, gotchas 180–185 e ponteiros em panel/publishing/ai/tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 04:53:34 -03:00

285 lines
30 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` (`<accountId>--<platform>`). 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/<profileId>/`, `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` (`<dialog>` 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 = "<publish_jobs.id>:<attempts>"`; 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/<id>/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/<id>`, 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-<id>.<ext>`
(`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/<id>/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 `<a>`) 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/<id>/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/<id>`; YouTube shorts, `watch?v=` ou `youtu.be`, normalizado para `/shorts/<id>`;
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 é `<a>` com `<svg aria-label="Postar">` 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`: `/<conta>/` com `textContent` "Perfil" ou foto do
perfil no `alt`; a barra recolhida esconde o texto), abre `/<conta>/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 `/<conta>/reel/<código>/`. 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 `<button>` nativo: o Playwright clica mesmo desativado e o clique se perde.
`is_enabled`/`wait_enabled` leem `disabled`/`aria-disabled` do elemento e do `<button>` de dentro e esperam até 10 min;
`dismiss_tips` + `click_through` rodam antes do clique. `confirm_published(page, done, sleep, checks=45, retry_at=8)`
(45 checagens de 2 s) conta como publicado a caixa "Vídeo/Short publicado", "ainda está sendo processado" ou a caixa
de envio fechar (o botão sumir); se o botão continua na tela e liberado depois de ~16 s, clica de novo UMA vez (o
vídeo já existe, não duplica). O erro final traz o link visto antes do clique e manda usar "Já saiu: informar o link".
Teste: `test_youtube_confirms_when_upload_box_closes_and_retries_once` (`publisher/tests/test_browser.py`). Só vale
depois de reiniciar o `pnpm dev`; **não testado num envio real**.
## Números dos posts (views, curtidas, comentários)
Fluxo: despachante → `collectMetrics` → Publicador lê → grava `publication_metrics` (`simulated = 0`, `INSERT OR REPLACE`).
- **Publicador**: rota `POST /v1/profiles/{id}/stats`, corpo `{ids: [...]}`, resposta `{capturedAt, items[{remoteId, views,
likes, comments, shares, saves}], missing}` (`Publisher.post_stats` em `service.py`). Arquivos: `app/platforms/stats.py`
(`PostStats`, `parse_count`, `youtube_public`, `youtube_from_html`) e `app/platforms/session/stats.py` (`tiktok_stats`,
`tiktok_row_stats`, `instagram_stats`, `instagram_media`, `READERS`). `SessionRunner.read_stats` usa a trava de
navegador, espera um envio até 120 s e fecha a janela só se ela não estava aberta antes. Testes:
`publisher/tests/test_stats.py`; `pnpm test:publisher` → **83 passed** (reexecutado na skill, 17/11/2026).
- **Como cada rede é lida** (medido com conta real, 17/11/2026):
- YouTube: página pública `watch?v=` sem navegador dá `viewCount` e `likeCount` exatos; comentários só arredondados
("5,2 mil"). Funciona em qualquer modo.
- TikTok: a página pública devolve só verificação (1,4 KB): precisa da janela logada. Em `/tiktokstudio/content`, cada
linha `data-tt="components_RowLayout_FlexRow"` tem o link `/video/<id>` e termina em "Todos\n<views>\n<curtidas>\n<comentários>".
~4 s.
- Instagram: sem login não há números. Pela aba Reels do perfil a página chama `/api/graphql` com `code`, `play_count`
(views), `like_count`, `comment_count`; a grade mostra só views ("1.499"). **A grade aparece ANTES da resposta da API**:
parar ao achá-la perde curtidas e comentários. Por isso a API tem prioridade e a grade é reserva, depois de 3 voltas.
~15 s.
- Modo oficial do TikTok/Instagram: ainda não lê (409 "por enquanto só funciona no modo Sessão logada").
- `parse_count`: "1.499" → 1499, "1,2 mil" / "1.2K" → 1200, "3,4 mi" → 3400000.
- **Painel**: migração **v8** (`metric_syncs`: account_id, platform, last_run_at, last_ok_at, last_error, read_count,
missing_count). `panel/src/lib/metrics-sync.ts`: `collectMetrics({accountId?, force?})` nunca roda duas ao mesmo tempo
(estado em `globalThis`) e para em 503; `autoCollectMetrics` é chamado sem `await` no fim do `dispatcherTick`, no máximo
a cada 10 min. Configuração `metricsEveryHours` (0/3/6/12/24; padrão 6; `app_settings.metrics_every_hours`): a automática
lê só posts dos últimos 90 dias; o botão lê todos. Rota `/api/dashboard/metrics`: GET `{running, syncs}`; POST lê tudo agora.
`lib/metrics.ts` `dashboard()` ganhou `byVideo` (um por corte/episódio, total e números por rede; título de
`publish_jobs.title`) e `syncs`.
- **UI**: `VideoTable` (`components/metrics-view.tsx`: colunas YouTube/TikTok/Instagram com link, total, curtidas,
comentários); `MetricsSyncControls` (`dashboard-controls.tsx`: "Atualizar números agora", "lido há X h" ou o erro de
cada rede); card "Números das redes" em Configurações → Publicação. Cards de episódio e história somem sem dados.
- Painel: `test:panel` 66/66 e typecheck verde (informados, não reexecutados). Não verificado: leitura automática com o
painel ao vivo.
## Botão "Publicar no <rede>" nos cartões de Publicações
`components/publishing-board.tsx`: para cortes, mostra as redes conectadas e ligadas do canal que ainda não têm job do
corte (job cancelado conta como livre). Confirma com `askConfirm` e chama `publishClip(clipId, {accountId, platforms:
[rede], timing})` com o timing do canal ("now" ou "best_slot"). O quadro carrega `/api/accounts` junto com o status.
## Fatos das plataformas (resumo; detalhe e fontes em `doc/publicacao/PESQUISA.md`)
- YouTube: projeto não verificado já publica público (desde 02/11/2026); `videos.insert` 100 envios/dia; app em
"Testing" perde a autorização em 7 dias (pôr "In production").
- TikTok: sem auditoria, Direct Post só `SELF_ONLY` (conta privada) ou rascunho (até 5 pendentes/24 h); auditoria
para uso próprio provavelmente negada.
- Instagram: conta Profissional; conta própria sem App Review; token colado (a Meta não aceita redirect localhost),
vale 60 dias, renovado quando faltam < 10; `rupload` com arquivo local via `graph.instagram.com` ainda **a testar**.
## Evidência (17/11/2026)
Depois das revisões de segurança e correção, reconferido pela skill: `pnpm test:publisher` → 71 passed (depois da correção do Chrome 157, informado: 73 passed; gotchas 137);
`pnpm --filter cenaforge-panel test:panel` → 59/59; typecheck do painel e da raiz sem erro (informados também:
`test:launcher` 17/17, `test:clipper` 270 passed). Bancos reais: `data/cenaforge.db` ainda em `user_version` 5 (a v6
entrava só com o painel reaberto; hoje a 1ª requisição depois da recarga do `db.ts` migra — gotchas, itens 51 e 138); `data/publisher/publisher.db` em 2. Não
verificado: conexão de qualquer rede pela UI (nos dois modos), envio real, renovação de token, seletores do modo
sessão, laço do despachante com o painel ao vivo, fechamento da janela do navegador num envio real.
Botão "Publicar" do corte (informado, 17/11/2026; não reexecutado aqui): typecheck do painel verde; `test:panel` 63/63,
com testes novos em `publishing-rules.test.ts` ("publicado à mão (origin manual)…") e em `publishing-db.test.ts`
(seção "Publicar" no cartão do corte: job manual com rede não conectada pulada, `endChannel` não cancela o manual,
recusas); teste de migração agora espera a v7. **Não testado com conta real.** Plano: `doc/publicacao/PLANO.md` §7c.
Envio de arquivo grande no modo sessão (informado e reconferido, 17/11/2026): a 1ª tentativa real no TikTok chegou ao
TikTok Studio logado e falhou em `set_input_files` (> 50 MB, gotchas 139). Correção `is_local=True` aplicada;
`pnpm test:publisher` → 73 passed (então). O envio real depois disso funcionou (ver "Primeiro envio real" acima).
Link do TikTok e "Já saiu" (informado, 17/11/2026): `pnpm test:publisher` → **74 passed** (reexecutado na skill; teste novo
`test_tiktok_link_waits_for_the_list_and_matches_caption` em `publisher/tests/test_browser.py`); `test:panel` 65/65 e
typecheck verdes (informados, não reexecutados); `parseVideoUrl` em `publishing-rules.test.ts`, `markPublished` em
`publishing-db.test.ts`. `find_video_url` validado ao vivo só de leitura na lista real (informado): a legenda certa
devolveu o link, a de outro corte `None`. **`find_video_url` e `is_local` só valem depois de reiniciar o `pnpm dev`.**
Espera do link com recarga da lista (informado, 17/11/2026): `find_video_url` com 12 cargas × 5 leituras; validado ao vivo,
só leitura, achou `https://www.tiktok.com/@vortplay/video/7709183805373877524` (2º post real, 13:50); o job 1 foi marcado
publicado por `mark-published`. `pnpm test:publisher` → **76 passed** (reexecutado; teste
`test_tiktok_link_waits_for_the_list_and_matches_caption` agora recarrega e confere "2 de 12"). `test:panel` 65/65 e typecheck
verdes (informados, não reexecutados; teste novo da mensagem "Saiu na rede…"). **O envio das 13:50 rodou código antigo** (gotchas
143): a espera nova ainda **não foi exercitada num envio real**.
Aviso por cima da legenda (informado e reconferido, 17/11/2026): o 2º envio real no TikTok (captura `20261117-134508`)
falhou no clique da legenda por causa do aviso "Entendi" (gotchas 142); o upload de 100+ MB passou (`is_local` valendo).
`pnpm test:publisher` → **76 passed** (reexecutado; testes novos `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures`). O post não chegou a ser feito; **correção não testada num envio
real e só vale depois de reiniciar o `pnpm dev`.**
Instagram em modo sessão (informado e reconferido, 17/11/2026): `pnpm test:publisher` → **78 passed** (reexecutado; testes
novos `test_instagram_links_and_hashtag_suggestions` e `test_buttons_of_the_flow_are_searched_inside_the_dialog` em
`publisher/tests/test_browser.py`). Ensaio ao vivo sem publicar: ver regra "Instagram em modo sessão". O "Já entrei" do
usuário falhou porque o Publicador rodava código antigo (gotchas 143): reiniciar o `pnpm dev`.
1º reel real e formato (informado, 17/11/2026): o reel `/reel/Df2cezTNhY7/` (corte 68) saiu 1:1; o usuário o apagou e a
página mostra "Esta página não está disponível" (conferido). Corrigido com `keep_original_shape` (gotchas 147); ensaio sem
publicar validou a prévia 9:16 inteira com legenda e rótulo de IA; rascunho descartado. `pnpm test:publisher` → **78 passed**
(reexecutado). `test:panel` 66/66 e typecheck verdes (informados, não reexecutados; teste novo de `markRemoved`).
**Formato "Original" só vale depois de reiniciar o `pnpm dev`; o painel (`removed`, corte sem rótulo) já vale.** Não validado:
publicação real com o formato novo.