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>
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# Publicação nas redes — pesquisa de 17/11/2026
|
||||
|
||||
[C] = confirmado em página oficial · [S] = fonte secundária / a testar. Reverificar a cada 3 meses.
|
||||
|
||||
## YouTube (Data API v3)
|
||||
|
||||
- **Projeto não verificado já publica público** desde 02/11/2026 (revision history) [C]. Sem `privacyStatus` ⇒ `public`.
|
||||
- Cota: desde 01/06/2026 `videos.insert` tem balde próprio de **100/dia** (custo 1); demais chamadas 10.000 unidades; zera meia-noite PT [C].
|
||||
- OAuth: cliente **"Desktop app"**, redirect loopback `http://127.0.0.1:<porta>` (qualquer porta), **PKCE sempre** [C]. Escopo mínimo `youtube.upload`.
|
||||
- Upload resumable (`uploadType=resumable`), `video/*` [C].
|
||||
- Metadados: `snippet.title/description/tags`; `status.privacyStatus`, `publishAt` (exige `private` e nunca publicado), `selfDeclaredMadeForKids`, **`containsSyntheticMedia`** [C].
|
||||
- `thumbnails.set` aceita capa personalizada em Shorts desde 03/11/2026, depois do processamento [C].
|
||||
- Vira Short: ≤ 3 min e vertical/quadrado; não existe campo "isShort" [C].
|
||||
- Tokens: app em **"Testing" expira autorização em 7 dias** (inclui refresh). Colocar o app em **"In production"** (mesmo sem verificação) resolve; aparece tela "app não verificado"; teto 100 usuários — irrelevante [C].
|
||||
- Libs: `google-api-python-client` 2.202.0, `google-auth-oauthlib` 1.5.0 (PyPI); `googleapis` 190.0.0 (npm) [C].
|
||||
|
||||
## TikTok (Content Posting API)
|
||||
|
||||
- OAuth desktop: host `localhost`/`127.0.0.1` com porta (curinga `*` aceito); **PKCE obrigatório, S256 com desafio em hex** do SHA-256 [C].
|
||||
- Access token 2 h; refresh 180 d **rotativo** — gravar sempre o novo [C].
|
||||
- Direct Post (`video.publish`): chamar antes `POST /v2/post/publish/creator_info/query/`. Campos: `title` (≤2200), `privacy_level` (obrigatório, vindo do creator_info), `disable_comment/duet/stitch`, `video_cover_timestamp_ms`, `brand_content_toggle`, `brand_organic_toggle`, **`is_aigc`** [C].
|
||||
- Rascunho (`video.upload`): `/v2/post/publish/inbox/video/init/`; vai para a caixa de entrada do app; máx. **5 pendentes/24 h** [C]. Funciona sem auditoria [S].
|
||||
- FILE_UPLOAD: PUT em blocos 5–64 MB (último até 128 MB), ≤ 4 GB, ≤ 10 min, 23–60 fps, `upload_url` vale 1 h. PULL_FROM_URL exige domínio verificado ⇒ **usar FILE_UPLOAD** [C].
|
||||
- 6 req/min por token; erro `spam_risk_too_many_posts` [C].
|
||||
- **Sem auditoria: só `SELF_ONLY`, a conta precisa estar privada, máx. 5 usuários/24 h** [C].
|
||||
- UI exigida pelo TikTok: mostrar apelido do criador; privacidade escolhida à mão **sem padrão**; interações desmarcadas; divulgação comercial; prévia; declaração de uso de música; sem marca d'água [C].
|
||||
- **Auditoria provavelmente negada**: a TikTok lista como inaceitável "utility tool to help upload contents to the account(s) you or your team manages" e apps de uso interno/privado [C].
|
||||
|
||||
## Instagram (Reels)
|
||||
|
||||
- Conta **Profissional** (Business/Creator) [C].
|
||||
- **Instagram API with Instagram Login**: sem Página do Facebook; host `graph.instagram.com`; escopos `instagram_business_basic`, `instagram_business_content_publish` [C].
|
||||
- Facebook Login for Business: exige Página; `graph.facebook.com` + `rupload.facebook.com` [C].
|
||||
- Upload resumable com **arquivo local** (rupload) é documentado "só para Facebook Login for Business"; com Instagram Login precisaria de `video_url` pública. Blogs mostram rupload funcionando com `graph.instagram.com` [C/S — **testar**].
|
||||
- Fluxo: container `media_type=REELS` → (rupload) → consultar `status_code` 1×/min até 5 min → `media_publish`; container expira em 24 h [C].
|
||||
- Campos: `caption`, `cover_url`, `thumb_offset`, `share_to_feed`, `audio_name`, `collaborators` (≤3), `trial_params`, **`is_ai_generated`** [C].
|
||||
- Vídeo: MP4/MOV com moov no início, H.264/HEVC, 23–60 fps, 3 s–15 min, ≤ 300 MB, 9:16 recomendado [C].
|
||||
- Limite: 100 posts/24 h (a página também cita 50); consultar `/content_publishing_limit` [C].
|
||||
- Conta própria ("I own or manage"): Standard Access, **sem App Review** [C].
|
||||
- Token longo 60 d, renovável por `refresh_access_token` (> 24 h de idade) [C].
|
||||
- Redirect precisa bater exatamente; a Meta **não aceita localhost** e pede HTTPS [S] ⇒ usar token gerado no painel de desenvolvedor.
|
||||
|
||||
## Modo sessão logada (sem API)
|
||||
|
||||
- **Viola os termos das três redes** (YouTube: "qualquer meio automatizado"; TikTok: "automated scripts"; Instagram: automação sem permissão) — risco de bloqueio/checkpoint é do usuário.
|
||||
- Bibliotecas: `tiktok-uploader` v1.2.0 (fev/2026, parada); `instagrapi` 3.2.15 (API privada do app móvel — **maior risco, não usar**); `youtube_uploader_selenium` (abandonada); `social-auto-upload` (depende de burla de detecção — **descartar**).
|
||||
- Abordagem honesta: Playwright com perfil **próprio e vazio** (automatizar o perfil padrão do Chrome não é suportado), navegador visível, **usuário loga à mão**, nunca automatizar senha/captcha.
|
||||
- O Google costuma bloquear login em navegador controlado por automação ("This browser or app may not be secure") [S] ⇒ abrir Chrome/Edge **normal** com `--user-data-dir` dedicado, o usuário loga, e só depois conectar via `connectOverCDP`.
|
||||
- Sessão expirada: redirecionamento para login, botão "Entrar/Log in" por role, ou ausência do campo de arquivo/botão "Criar".
|
||||
- Seletores: `getByRole`/`getByLabel`/`getByText` em PT e EN; screenshot e trace na falha; teste de fumaça que só abre a tela de upload. As telas mudam com frequência [S].
|
||||
|
||||
## Comparativo
|
||||
|
||||
| | Publica | Limitações | Risco |
|
||||
|---|---|---|---|
|
||||
| YouTube API | público, privado, agendado, Short automático | 100/dia; tela "não verificado" | baixo |
|
||||
| YouTube sessão | o mesmo pelo Studio | login Google pode ser bloqueado; UI muda | alto (termos) |
|
||||
| TikTok API | rascunho no app; Direct Post só SELF_ONLY sem auditoria | 5 rascunhos/24 h | baixo |
|
||||
| TikTok sessão | post público | captcha; UI instável | alto (termos) |
|
||||
| Instagram API | Reel público, capa, rótulo IA | token 60 d; rupload a testar | baixo |
|
||||
| Instagram sessão | Reel pelo site | checkpoints frequentes | alto (termos) |
|
||||
|
||||
## Fontes
|
||||
|
||||
developers.google.com/youtube/v3/revision_history · /docs/videos/insert · /docs/videos · /determine_quota_cost ·
|
||||
developers.google.com/identity/protocols/oauth2/native-app · support.google.com/cloud/answer/15549945 ·
|
||||
support.google.com/youtube/answer/15424877 · developers.tiktok.com/doc/content-posting-api-reference-direct-post ·
|
||||
/content-posting-api-reference-upload-video · /content-posting-api-media-transfer-guide · /content-sharing-guidelines ·
|
||||
/login-kit-desktop · /oauth-user-access-token-management · developers.facebook.com/docs/instagram-platform/content-publishing ·
|
||||
/content-publishing/resumable-uploads · /instagram-api-with-instagram-login · /app-review ·
|
||||
playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context
|
||||
@@ -0,0 +1,246 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user