Files
CenaForge/doc/publicacao/PLANO.md
T
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

247 lines
20 KiB
Markdown
Raw 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 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).