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

116 lines
7.8 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.
# Publicador do CenaForge
Serviço local (`127.0.0.1:4530`) que **envia os vídeos para YouTube, TikTok e Instagram**. Ele é só o *executor*:
recebe do painel um pedido de envio (arquivo + título/legenda + perfil), manda para a rede e devolve o progresso e o
link. Quem decide **o quê** e **quando** publicar é o painel (Canais de publicação, aprovação, horários bons).
Contrato HTTP e regras: [doc/publicacao/PLANO.md](../doc/publicacao/PLANO.md) (§3). Fatos das APIs:
[doc/publicacao/PESQUISA.md](../doc/publicacao/PESQUISA.md).
## Como rodar
- Instalação: `setup.bat` na raiz (cria `publisher/.venv` com Python 3.12 e `publisher/.env` com a chave).
- Subir: `start.bat` ou `pnpm dev` (sobe junto com o painel). Sem `.venv`/chave, o `pnpm dev` pula o Publicador com
um aviso.
- Testes: `pnpm test:publisher` (pytest, sem internet e sem abrir navegador).
- Só o serviço, à mão: `cd publisher && .venv\Scripts\python -m uvicorn app.main:build --factory --port 4530`.
O painel conversa com ele usando o cabeçalho `X-Service-Key` = `PUBLISHER_SERVICE_KEY` de `publisher/.env`.
## Envio sem duplicar
`POST /v1/jobs` aceita `clientRef` (até 80 caracteres, ex.: o id do job no painel). Se chegar de novo com o mesmo
`clientRef`, o Publicador devolve o job que já existe (HTTP 200, sem criar outro nem revalidar); um job novo volta
com 201. Vídeo e capa só são aceitos das pastas de saída (`output/`, `stories/`, `assets/`).
## Dois modos por rede (você escolhe perfil a perfil)
| | Conta oficial (API) | Sessão logada |
|---|---|---|
| Como conecta | autoriza na página da rede (YouTube, TikTok) ou cola um token (Instagram) | você entra na conta numa janela do Chrome/Edge aberta pelo CenaForge |
| Precisa criar app | sim (passo a passo abaixo) | não |
| Risco para a conta | baixo (caminho oficial) | **alto: viola os termos das três redes** (pode bloquear a conta) |
| Limites | YouTube 100 envios/dia; TikTok sem auditoria só privado ou rascunho | captcha/verificações; a tela das redes muda |
### Regras do modo sessão (não negociáveis)
- A janela do navegador é **visível** e **você faz o login à mão** (com 2FA normal). O CenaForge nunca vê, guarda ou
digita sua senha e **nunca** resolve captcha.
- Nada de "stealth", patchright, stealth.js ou qualquer burla de detecção de automação. Se a rede pedir login,
captcha ou "confirme que é você", o envio **para** em `needs_login` e o painel avisa — você resolve na janela e
clica em "Já entrei".
- Um envio por vez, com **intervalo mínimo entre envios** (30 s) e pausas curtas entre os passos. É só ritmo para
não sobrecarregar a conta — não é tentativa de imitar uma pessoa.
- A porta de depuração do navegador (4540–4549) dá controle total dele, então fica aberta o mínimo: a janela fecha
depois de cada envio, depois do "Já entrei" bem-sucedido e quando fica parada (5 min; 15 min se foi aberta para o
login). Antes de usar uma porta, o serviço confere que é o navegador DESTE perfil (`DevToolsActivePort` quando existe; no Chrome 157+ com porta
fixa ele não é gravado, então vale a marca `CenaForgeWindow.json` + o PID que escuta na porta).
- O navegador é o **seu Chrome** (ou Edge) instalado, aberto como programa normal com um perfil separado. O pacote
`playwright` entra só como "controle remoto" (`connect_over_cdp`); **não rode `playwright install`** — nada é baixado.
- Os seletores das telas (YouTube Studio, TikTok Studio, Instagram) ficam num dicionário `SELECTORS` no topo de cada
arquivo em `app/platforms/session/` e **ainda precisam ser validados com uma conta real**. Quando algo falha, há uma
captura só da área visível em `data/publisher/logs/` — nunca de tela de login, captcha ou verificação. Capturas com
mais de 7 dias são apagadas na subida do serviço.
## Criar o app de cada rede (modo oficial)
Os dados do app vão em **Configurações → Apps das redes** no painel (ou `PUT /v1/apps/{rede}`).
### YouTube (Google Cloud)
1. Em <https://console.cloud.google.com/> crie um projeto e ative a **YouTube Data API v3**.
2. Em "Tela de permissão OAuth" (Google Auth Platform), tipo **Externo**; adicione seu e-mail.
3. Em "Clientes", crie um cliente OAuth do tipo **App para computador (Desktop app)**. Copie o Client ID e o Client
Secret para o painel. O redirect usado é `http://127.0.0.1:4530/oauth/callback/youtube` (cliente Desktop aceita
loopback em qualquer porta, não precisa cadastrar).
4. Em "Público", clique em **Publicar app / In production**. Em "Testing" a autorização vence a cada 7 dias. Vai
aparecer a tela "o Google não verificou este app" — é o seu próprio app: "Avançado → continuar".
### TikTok (TikTok for Developers)
1. Em <https://developers.tiktok.com/> crie um app e adicione **Login Kit** (plataforma **Desktop**) e **Content
Posting API** (ative "Direct Post" se quiser publicar direto).
2. Cadastre o redirect `http://127.0.0.1:4530/oauth/callback/tiktok` e os escopos `user.info.basic`,
`video.upload`, `video.publish`.
3. Copie o **Client Key** (vai no campo Client ID) e o **Client Secret** para o painel.
4. **Sem auditoria do TikTok**, o Direct Post só sai como **privado (Somente eu)** e a conta precisa estar privada; o
serviço avisa: "O TikTok só permite publicar como privado (Somente eu) até o app ser auditado. Use o modo Rascunho
ou a Sessão logada." O modo **Rascunho** manda o vídeo para a caixa de entrada do app (até 5 pendentes por dia) e
você publica pelo celular. A auditoria provavelmente é negada para uso próprio.
### Instagram (Meta for Developers)
1. A conta do Instagram precisa ser **Profissional** (Criador de conteúdo ou Empresa).
2. Em <https://developers.facebook.com/> crie um app e adicione o produto **Instagram → "API setup with Instagram
login"** (Instagram API with Instagram Login). Permissões: `instagram_business_basic`,
`instagram_business_content_publish`.
3. Em "Generate access tokens", adicione sua conta e clique em **Generate token**. Copie o token e cole em Canais de
publicação → Instagram → Conta oficial. (A Meta não aceita redirect para `localhost`, por isso o token é colado.)
4. O token vale 60 dias; o Publicador renova sozinho quando faltam menos de 10 dias (se estiver ligado).
5. O envio usa o upload do arquivo local (`rupload`). A Meta documenta isso só para "Facebook Login for Business";
se a rede recusar, o erro diz isso com clareza e a saída é usar a Sessão logada (ou o Facebook Login).
## Onde ficam os dados
Tudo em `data/publisher/` (fora do controle de versão):
| Caminho | O quê |
|---|---|
| `publisher.db` | perfis, jobs de envio e os `state` do OAuth (SQLite) |
| `vault.bin` | **segredos** (tokens, client secret) cifrados com a DPAPI do Windows — só o seu usuário, nesta máquina, abre |
| `browser/<perfil>/` | perfil do Chrome/Edge do modo sessão (cookies = sua sessão logada). "Desconectar" apaga a pasta |
| `logs/` | capturas de tela das falhas do modo sessão (apagadas após 7 dias) |
Permissões: o `setup.bat` deixa `publisher/.env` e `data/publisher/` acessíveis só ao seu usuário do Windows
(`icacls /inheritance:r`); se a pasta não existir, o próprio serviço a cria assim na primeira subida.
Os segredos nunca voltam pela API (só `configured: true/false`). Se o Publicador for fechado no meio de um envio, o
job vira `failed` com "interrompido — tente de novo" (não dá para saber se chegou à rede: confira antes).
## Arquivos
- `app/main.py` rotas · `app/service.py` regras · `app/worker.py` fila (uma thread, um job por vez)
- `app/db.py` SQLite · `app/vault.py` cofre DPAPI · `app/paths.py` só aceita vídeo/capa de `output/`, `stories/` e `assets/` (recusa `data/`)
- `app/platforms/{youtube,tiktok,instagram}_api.py` APIs oficiais
- `app/platforms/session/` navegador (`browser.py`), execução (`runner.py`) e um uploader por rede