# 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 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 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 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 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