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>
247 lines
20 KiB
Markdown
247 lines
20 KiB
Markdown
# 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 = "<accountId>--<platform>"` (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": "<mensagem em pt-BR>" }` 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/<profileId> --remote-debugging-port=<livre em 4540–4549> --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) = `"<publish_jobs.id>:<attempts>"`. 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).
|