BK-152 — Contrato Unico: Prova de Rascunho, Screenshot, Checklist e Estados

Status

FASE 1 CONCLUÍDA — Contrato canônico publicado em docs/architecture/CONTRATO-PROVA-RASCUNHO.md

RECONCILIAÇÃO DOCUMENTAL CONCLUÍDA — Alinhamento com auditoria do RNT validado

FECHAMENTO DOCUMENTAL CONCLUÍDO — Seção 5.3 preenchida com follow-ups mapeados

1. Problema

O BK-152 tem como objetivo padronizar o conceito de draft_url, post_url, screenshot/prova, checklist manual e estados entre Studio, WhatsApp, fila e browser/manual step. O problema central e que nao existe contrato unico canonico que defina formalmente:

• O que constitui uma "prova de rascunho" valida
• Quais campos obrigatorios compoem o estado de um post em rascunho
• Como a prova é armazenada, referenciada e transmitida entre Studio, WhatsApp e fila
• Quais os estados validos (draft, pending_approval, approved, published, failed)
• Quando o fallback browser é acionado e como ele se integra ao fluxo de aprovacao

Ha implementacoes parciais dispersas entre RNT e Cerebro, mas faltam definicoes canonicas que garantam consistência.

2. Estado Atual Confirmado

2.1 RNT — admin/cron/sync_facebook_events.php

Ja expoe browser_draft_proof com a seguinte estrutura:

```php

$event['browser_draft_proof'] = [

'draft_url' => $draftUrl,

'screenshot_path' => $screenshotPath,

'artifact_dir' => $artifactDir,

'run_id' => $runId,

'storage_state_path' => $storageStatePath,

'output_root' => $outputRoot,

'command' => $command,

'runner_ok' => $runnerOk,

'runner_exit_code' => $runnerExitCode,

'notification_sent_at' => $notificationSentAt,

'notification_result' => $notificationResult

];

```

Confirmado: O RNT ja gera e armazena a prova do rascunho, incluindo screenshot, URL e metadados de execucao.

2.2 RNT — Fluxo de Aprovacao com Fila

Ha implementacao de fila/aprovacao com:

• pending_approval — flag indicando que o post aguarda aprovacao
• approval_stage=pre_whatsapp — estagio onde o WhatsApp e acionado antes da publicacao
• WhatsApp de aprovacao: mensagem enviada ao responsavel com a prova do rascunho
• Fallback browser: em caso de falha no WhatsApp, o sistema faz fallback para browser via:
• admin/modulos/campanhas/redes_sociais_ui_helper.php
• action_squad.php

Confirmado: O RNT ja implementa fluxo de aprovacao com notificação WhatsApp e fallback browser.

2.3 Cerebro — Studio

O Studio ja tem:

• Superficies de aprovacao (dashboards com botoes de aprovar/rejeitar)
• Backlog de posts pendentes
• Visualizacao de screenshots e URLs de rascunho

Confirmado: O Studio expoe UI para visualizacao e aprovacao.

2.4 Cerebro — Kernel/Browser Runtime

O kernel/browser runtime ja produz:

• Artefatos browser (screenshots, states, logs)
• Armazenamento em disco (artifact_dir, screenshot_path)
• Execucao de comandos via browser profile

Confirmado: O Cerebro gera artefatos browser que podem servir como prova.

3. Lacunas que Impedem Chamar Isso de Contrato Unico

3.1 Ausencia de Schema Canonico

• Nao ha definicao formal de quais campos sao obrigatorios para uma prova de rascunho valida
• O schema em sync_facebook_events.php existe, mas nao esta documentado como "contrato"
• Nao existe validacao centralizada que enforce o schema

3.2 Inconsistencia de Terminologia

• draft_url vs post_url — quais campos realmente diferem?
• browser_draft_proof vs proof vs prova — nomenclatura varia entre modulos
• pending_approval vs approval_stage — relacao entre campos nao explicita

3.3 Falta de Estado Centralizado

• Cada modulo (Studio, WhatsApp, fila, browser) mantem proprio estado
• Nao ha fonte unica de verdade para o status de um post
• Sincronizacao entre modulos depende de implementacoes ad-hoc

3.4 Ausencia de Contrato de Interface

• WhatsApp nao tem contrato formal de como recebe a prova
• Browser fallback nao tem spec de quando e como e acionado
• Studio nao expõe API documentada para consulta de estado

3.5 Checklist Manual Nao Formalizado

• Nao ha checklist canonico de itens a verificar na prova do rascunho
• O que constitui "prova suficiente" varia por contexto
• Nao ha validacao automatica do checklist

4. Tese do Menor Corte para Fechar BK-152 com Seguranca

Tese: Criar um documento de arquitetura/contrato que formalize o schema existente do RNT (browser_draft_proof) como o contrato unico canonico de prova de rascunho, e definir os estados e fluxos restantes como extensoes desse contrato, sem modificar codigo na primeira fase.

Menor corte proposto:

1. Formalizar o schema existente como "contrato unico" em documentacao
2. Definir os 4 estados validos: draft, pending_approval, approved, published/failed
3. Mapear cada modulo (Studio, WhatsApp, fila, browser) ao contrato
4. Documentar o fluxo de aprovacao + fallback browser
5. Definir checklist basico de itens que compoem uma prova valida
6. Nao alterar codigo nesta fase — apenas documentar o que ja existe e funciona

Por que menor corte: O codigo ja funciona (RNT gera provas, Studio aprova, WhatsApp notifica, fallback existe). O que falta e a formalizacao conceitual que permita chamar isso de "contrato unico" com seguranca.

5. Criterios de Aceite Mensuraveis

5.1 Documentacao do Contrato

• [x] Documento de arquitetura publicando browser_draft_proof como schema canonico
• [x] Definicao dos 4 estados validos com transicoes documentadas
• [x] Mapeamento de cada modulo ao contrato
• [x] Descricao do fluxo de aprovacao + fallback browser
• [x] Checklist de itens obrigatorios em uma prova

5.2 Revisao de Alinhamento

• [x] Codigo existente (RNT + Cerebro) corresponde ao contrato documentado
• [x] Nao ha divergencias criticas entre schema documentado e implementacao
• [x] Fluxo de aprovacao descrito corresponde ao comportamento real

Auditoria de alinhamento (2026-04-09):

• Schema do browser_draft_proof fortemente alinhado com implementação real
• Ponto de atenção: approval_stage não é populado no payload canônico atual — tratado como lacuna de compatibilidade/follow-up, não como bloqueio crítico
• Estados mais granulares no RNT (queued, scheduled, pending_approval, notified, posted, posted_manual, failed, error, canceled) mapeados para estados canônicos mínimos no contrato
• Sem divergência crítica que impeça o fluxo operacional

5.3 Proxima Fase Identificada

As lacunas já mapeadas no contrato canônico (Seção 8 de docs/architecture/CONTRATO-PROVA-RASCUNHO.md) são:

| # | Lacuna | Descrição |

|---|---|---|

| 1 | Validação centralizada do schema | Não há enforce do schema em camada única. Validação distribuída entre módulos. |

| 2 | API de consulta no Studio | Studio não expõe API documentada para consumo do contrato por sistemas externos. |

| 3 | Histórico/audit trail de transições | Não há persistência de audit trail (quando mudou de status, quem aprovou, etc.). |

| 4 | Contrato formal da notificação WhatsApp | Input/format da mensagem não está formalizado em spec. |

| 5 | Condição explícita do browser fallback | Condição exata de acionamento do fallback não está documentada em contrato. |

| 6 | Harmonização do approval_stage | Campo opcional no schema atual mas não populado no payload canônico — harmonização futura. |

Recomendação: As lacunas acima são de natureza evolutiva e não bloqueiam o contrato canônico publicado na Fase 1. O BK-152 alcançou seu objetivo de formalização documental com segurança.

STATUS DO BK-152: ✅ CONCLUÍDO DOCUMENTALMENTE — Fase 1 finalizada.

6. Path List Inicial

```text

docs/backlog/BK-152-contrato-unico-prova-rascunho-publish.md # Este arquivo

docs/architecture/CONTRATO-PROVA-RASCUNHO.md # Contrato canônico (CRIADO - artefato principal da fase 1)

```

6.1 Artefato Principal da Fase 1

O contrato canônico foi publicado em:

• Caminho: docs/architecture/CONTRATO-PROVA-RASCUNHO.md
• Status: Criado e disponível

O contrato inclui:

• Schema canônico mínimo (14 campos)
• Estados válidos e transições
• Checklist mínimo de prova válida
• Mapeamento por superfície (RNT fila/cron, WhatsApp, browser/manual step, Studio)
• Regras práticas para tolerância de ausência de draft_url
• Lacunas identificadas para follow-up

7. Referencias Concretas aos Arquivos Reais

RNT

1. admin/cron/sync_facebook_events.php

• Contem: browser_draft_proof schema com todos os campos citados
• Referencia: $event['browser_draft_proof'] = [...]
• Status: Ja implementa geracao e armazenamento de prova

1. admin/modulos/campanhas/redes_sociais_ui_helper.php

• Contem: Superficie de UI para visualizacao e aprovacao
• Referencia: fluxo de aprovacao com WhatsApp e fallback

1. action_squad.php

• Contem: Handler de acoes da fila social, incluindo fallback browser
• Referencia: notificação e execucao de fallback

Cerebro

1. kernel/browser_control.js

• Contem: Runtime browser que gera artefatos (screenshots, states)
• Referencia: execucao de comandos e armazenamento de outputs

1. kernel/browser_executor.js

• Contem: Executor de comandos browser com tratamento de timeout e extract_url
• Referencia: execucao que produz a prova

1. studio/

• Contem: Superficies de aprovacao, backlog e visualizacao de screenshots
• Referencia: UI que consome as provas geradas pelo kernel

Historico

| data | evento |

|---|---|

| 2026-04-09 20:30 -03 | Backlog vivo criado a partir do estado real de RNT + Cerebro |