jhonny-editor/code/engine/arquitetura/plano-primeira-etapa-scanner-e-mcp.md

# Plano de Desenvolvimento — Primeira Etapa

## Scanner e leitura da timeline via MCP

## Status

Plano de desenvolvimento da primeira etapa. Este documento organiza a implementação futura; não autoriza a criação imediata de código sem que cada fase esteja preparada e validada.

## Objetivo

Construir o primeiro fluxo funcional do sistema capaz de ler a timeline ativa do Premiere por meio do MCP e transformá-la em uma representação interna confiável.

Ao final desta etapa, o sistema deverá conseguir:

1. comunicar-se com o MCP;
2. verificar a disponibilidade do Premiere;
3. ler a sequência ativa, faixas e clipes;
4. converter respostas externas em objetos do domínio;
5. validar dados incompletos ou inválidos;
6. executar a descoberta por meio do `Scanner`;
7. registrar erros e informações relevantes;
8. testar todo o fluxo sem depender do Premiere real.

## Limites da etapa

### Incluído

- conexão e chamadas técnicas ao MCP;
- sessão e erros da integração;
- leitura da timeline, sequência, faixas e clipes;
- conversores de dados externos;
- entidades e objetos de valor necessários;
- contrato de acesso ao editor;
- contexto, pipeline e descoberta da timeline;
- configuração mínima do scanner;
- logs técnicos e de fluxo;
- testes unitários, de integração simulada e de conversores;
- fixtures baseadas em respostas reais do MCP.

### Não incluído

- corte, exclusão ou movimentação de clipes;
- qualquer escrita no Premiere;
- plano de edição;
- decisão automática;
- transcrição;
- análise visual;
- análise de áudio;
- detecção de cenas;
- detecção de retakes;
- uso obrigatório de provider de IA;
- otimizações prematuras ou execução paralela.

## Estrutura planejada

```text
engine/
├── arquitetura/
│   └── documentação da arquitetura
├── scanner/
│   ├── coordenacao/
│   ├── contratos/
│   ├── modelos/
│   ├── configuracao/
│   └── descoberta/
├── integracoes/
│   └── premiere/
│       ├── cliente_mcp.py
│       ├── sessao_mcp.py
│       ├── erros_mcp.py
│       ├── leitura/
│       ├── conversores/
│       └── contratos/
├── dominio/
│   ├── entidades/
│   └── objetos_de_valor/
├── configuracao/
├── persistencia/
├── logging/
└── testes/
```

## Fases de desenvolvimento

### Fase 0 — Preparação e confirmação arquitetural

**Objetivo:** garantir que o desenho está coerente antes da implementação.

**Atividades:**

- revisar `scanner.md`, `integracao-com-premiere.md` e `leitura-da-timeline-via-mcp.md`;
- revisar a skill `boas-praticas-oo.md`;
- confirmar que todos os identificadores internos serão em PT-BR;
- definir os contratos antes das implementações concretas;
- confirmar que o scanner não terá dependência direta do MCP;
- identificar quais classes são realmente necessárias na primeira versão.

**Entrega:** arquitetura aprovada e sem responsabilidades sobrepostas.

### Fase 1 — Descoberta da API real do MCP

**Objetivo:** conhecer o contrato externo antes de criar adaptadores definitivos.

**Atividades:**

- identificar como o MCP é iniciado;
- verificar como a conexão é estabelecida;
- listar as ferramentas disponíveis;
- identificar ferramentas para projeto, sequência, faixas e clipes;
- registrar argumentos, respostas e erros;
- observar formato dos identificadores e dos tempos;
- capturar respostas reais anonimizadas para fixtures;
- confirmar se a comunicação é síncrona ou assíncrona;
- confirmar se existe estado de sessão.

**Regra:** nomes de ferramentas e campos externos não serão inventados. Eles ficarão isolados na integração.

**Entrega:** inventário do MCP e conjunto inicial de fixtures reais.

### Fase 2 — Contratos e modelos do domínio

**Objetivo:** definir as interfaces internas antes dos adaptadores.

**Contratos:**

- `ContratoDeAcessoAoEditor`;
- contrato de etapa do scanner;
- contrato de conversor, quando necessário.

**Entidades:**

- `Projeto`;
- `Sequencia`;
- `Timeline`;
- `Faixa`;
- `Clipe`.

**Objetos de valor:**

- `IntervaloDeTempo`;
- `TipoDeFaixa`;
- `TipoDeMidia`;
- identificadores internos e externos, se necessário.

**Invariantes mínimas:**

- intervalo não pode iniciar antes de zero;
- fim não pode ser anterior ao início;
- identificadores devem ser preservados;
- posição na timeline e posição na origem são distintas;
- clipe pode estar offline sem invalidar toda a timeline;
- nome não é identificador único.

**Entrega:** modelo interno independente de MCP e editor.

### Fase 3 — Cliente e sessão MCP

**Objetivo:** encapsular a comunicação técnica externa.

**Classes:**

- `ClienteMCP`;
- `SessaoMCP`;
- `ErroMCP`;
- `ErroDeConexaoMCP`;
- `ErroDeFerramentaMCP`;
- `ErroDeRespostaMCP`;
- `FerramentaMCPNaoEncontrada`.

**Responsabilidades:**

- conectar e desconectar;
- informar estado da conexão;
- chamar ferramentas;
- controlar timeout;
- retornar resposta bruta;
- traduzir falhas técnicas em erros específicos;
- registrar logs técnicos.

**Restrições:**

- não criar entidades de domínio;
- não conhecer timeline, clipe, cena ou retake;
- não decidir qual ferramenta usar para uma regra de negócio;
- não misturar leitura e escrita.

**Entrega:** comunicação técnica testável com cliente simulado.

### Fase 4 — Leitura estruturada do Premiere

**Objetivo:** oferecer operações de alto nível para o restante do sistema.

**Classes iniciais:**

- `AcessoAoEditor`;
- `AcessoATimeline`;
- `AcessoAClipes`.

**Operações iniciais:**

- obter timeline ativa;
- obter sequência ativa;
- obter faixas;
- obter clipes;
- obter detalhes de um clipe.

Essas classes poderão começar com uma fachada simples e ser divididas somente quando houver crescimento real de responsabilidade.

**Entrega:** leitura sem que o scanner conheça nomes de ferramentas MCP.

### Fase 5 — Conversão e validação

**Objetivo:** transformar respostas externas em objetos internos confiáveis.

**Classes:**

- `ConversorDeTimeline`;
- `ConversorDeFaixas`;
- `ConversorDeClipes`.

**Atividades:**

- normalizar nomes de campos;
- converter tempos e identificadores;
- aplicar valores padrão seguros;
- validar campos obrigatórios;
- preservar campos externos relevantes;
- tratar tipos desconhecidos;
- diferenciar resposta incompleta de timeline vazia;
- gerar erros de validação estruturados.

**Entrega:** timeline de domínio construída a partir de fixtures externas.

### Fase 6 — Núcleo do scanner

**Objetivo:** executar a descoberta por meio do fluxo arquitetural definido.

**Classes:**

- `ContextoDeAnalise`;
- `Analisador`;
- `ResultadoDaAnalise`;
- `StatusDaAnalise`;
- `ErroDeAnalise`;
- `DescobertaDaTimeline`;
- `PipelineDoScanner`;
- `AnalisadorDeTimeline`.

**Fluxo:**

```text
AnalisadorDeTimeline
    ↓
ContextoDeAnalise
    ↓
PipelineDoScanner
    ↓
DescobertaDaTimeline
    ↓
ContratoDeAcessoAoEditor
    ↓
Timeline do domínio
    ↓
Contexto atualizado
```

Na primeira versão, o pipeline poderá conter somente `DescobertaDaTimeline`.

**Entrega:** scanner capaz de retornar o contexto com a timeline lida.

### Fase 7 — Testes e integração simulada

**Objetivo:** garantir comportamento sem depender do Premiere real.

**Implementar:**

- `AcessoAoEditorSimulado`;
- fixtures de projeto, sequência, faixas e clipes;
- testes do cliente MCP;
- testes dos acessos de leitura;
- testes dos conversores;
- testes das entidades e objetos de valor;
- testes do pipeline;
- testes da descoberta;
- testes de integração simulada.

**Cenários obrigatórios:**

- timeline válida;
- timeline vazia;
- nenhuma sequência ativa;
- sequência sem clipes;
- mídia offline;
- resposta incompleta;
- intervalo inválido;
- ferramenta inexistente;
- timeout;
- MCP indisponível;
- campos adicionais desconhecidos.

**Entrega:** suíte automatizada reproduzível.

### Fase 8 — Validação com Premiere real

**Objetivo:** confirmar o fluxo contra o ambiente real.

**Atividades:**

- conectar ao MCP real;
- listar ferramentas e comparar com o inventário;
- ler projeto e sequência reais;
- comparar resposta real com fixtures;
- validar faixas e clipes;
- testar projeto vazio;
- testar mídia offline;
- verificar logs sem dados sensíveis;
- confirmar que nenhuma ferramenta de escrita foi chamada.

**Entrega:** relatório de validação da leitura real.

## Critérios de conclusão

A primeira etapa estará concluída quando:

- o scanner depender apenas de contratos internos;
- o MCP estiver isolado no módulo de integração;
- a timeline ativa puder ser lida do Premiere;
- faixas e clipes forem convertidos para o domínio;
- intervalos da timeline e da origem forem preservados separadamente;
- mídia offline for representada sem interromper toda a leitura;
- timeline vazia for tratada como resultado válido quando apropriado;
- erros técnicos e de validação forem distinguíveis;
- o fluxo puder ser executado com integração simulada;
- os testes automatizados estiverem passando;
- os logs forem úteis e seguros;
- nenhuma alteração for feita na timeline;
- todos os identificadores internos respeitarem PT-BR;
- a implementação estiver aderente à skill de boas práticas OO.

## Ordem resumida

```text
Arquitetura
    ↓
API real do MCP
    ↓
Contratos e domínio
    ↓
ClienteMCP
    ↓
AcessoAoEditor
    ↓
Conversores
    ↓
Contexto e pipeline
    ↓
DescobertaDaTimeline
    ↓
Testes simulados
    ↓
Validação com Premiere real
```

## Regra final

O MCP é o mecanismo de comunicação com o editor. O scanner é o módulo que organiza a descoberta. O domínio representa os dados. Os conversores isolam formatos externos. Nenhuma dessas responsabilidades deve ser concentrada em uma única classe.