jhonny-editor/code/engine/arquitetura/planos-proximas-etapas.md

# Planos das Próximas Etapas

## Visão geral

O desenvolvimento será incremental. Cada etapa deverá produzir uma capacidade funcional verificável, com testes e integração controlada. Nenhuma etapa deverá antecipar responsabilidades de etapas posteriores.

## Etapa 1 — Concluir a leitura da timeline

### Objetivo

Produzir uma representação interna completa e confiável da sequência ativa do Premiere.

### Implementar

- `SessaoMCP`;
- `AcessoASequencia`;
- `AcessoAFaixas`;
- `AcessoAClipes`;
- `ConversorDeFaixas`;
- `ConversorDeClipes`;
- `ConversorDeRespostas`;
- `ResultadoDaAnalise`;
- `StatusDaAnalise`;
- `ErroDeAnalise`;
- validação estruturada;
- fixtures de respostas reais;
- persistência inicial do resultado.

### Resultado esperado

```text
Premiere → MCP → Domínio → ContextoDeAnalise
```

Sem cortes, alterações ou decisões editoriais.

## Etapa 2 — Descoberta de arquivos e metadados

### Objetivo

Relacionar cada clipe ao arquivo de origem e obter suas características técnicas.

### Implementar

- `DescobertaDeArquivos`;
- `ExtracaoDeMetadados`;
- adaptador para leitura de arquivos;
- identificação de mídia offline;
- codecs, resolução, duração e taxa de quadros;
- validação de arquivos inacessíveis;
- cache de metadados;
- testes com arquivos reais e simulados.

### Regra

O módulo não deverá avaliar qualidade artística nem decidir se um clipe deve ser usado.

## Etapa 3 — Extração e análise de áudio

### Objetivo

Preparar o áudio e gerar informações temporais sobre o sinal sonoro.

### Implementar

- `ExtracaoDeAudio`;
- `AnaliseDeAudio`;
- contratos de provider de áudio;
- adaptador para FFmpeg ou ferramenta definida;
- silêncio, pausas, volume, clipping e ruído;
- marcadores temporais;
- arquivos intermediários e limpeza segura;
- testes sem dependência do Premiere.

### Regra

Esta etapa não transcreve e não decide cortes.

## Etapa 4 — Transcrição

### Objetivo

Produzir texto sincronizado com o áudio dos clipes.

### Implementar

- `TranscricaoDeAudio`;
- `ProviderDeTranscricao`;
- primeiro adaptador de transcrição;
- segmentos, palavras e confiança;
- associação entre transcrição e clipe;
- cache e retomada;
- tratamento de falha parcial;
- testes com provider simulado.

### Regra

O scanner armazenará a transcrição, mas não decidirá cortes com base nela.

## Etapa 5 — Extração e análise visual

### Objetivo

Obter quadros representativos e características visuais dos clipes.

### Implementar

- `ExtracaoDeQuadros`;
- `AnaliseVisual`;
- `ProviderDeAnaliseVisual`;
- seleção temporal de quadros;
- cache de imagens;
- foco, exposição, estabilidade, pessoas e composição;
- confiança e referências temporais;
- testes com provider simulado.

## Etapa 6 — Cenas e eventos

### Objetivo

Consolidar sinais de vídeo, áudio e texto em cenas e eventos temporais.

### Implementar

- `DeteccaoDeCenas`;
- `DeteccaoDeEventos`;
- contratos de providers;
- combinação de resultados;
- deduplicação;
- confiança;
- eventos de fala, silêncio, pausas e mudanças visuais;
- testes de consolidação.

### Regra

Evento detectado é informação. Não é decisão de edição.

## Etapa 7 — Detecção de retakes

### Objetivo

Identificar possíveis tomadas repetidas ou alternativas.

### Implementar

- `DeteccaoDeRetakes`;
- comparação de transcrições;
- comparação visual;
- comparação de áudio;
- agrupamento de tomadas semelhantes;
- nível de similaridade;
- vínculos entre clipes e grupos de retake;
- testes com casos positivos e negativos.

## Etapa 8 — Persistência e reprocessamento

### Objetivo

Permitir salvar, consultar e retomar análises.

### Implementar

- contrato de repositório da análise;
- armazenamento da versão do scanner;
- armazenamento da configuração utilizada;
- revisão da timeline;
- cache por etapa;
- retomada após falha;
- invalidação seletiva;
- persistência de erros e avisos.

## Etapa 9 — Motor de decisão

### Objetivo

Interpretar os resultados do scanner e escolher ações editoriais.

### Implementar somente após o scanner

- `MotorDeDecisao`;
- regras editoriais;
- critérios de seleção;
- explicação das decisões;
- conflitos entre regras;
- nível de confiança;
- saída estruturada.

### Regra

O motor de decisão não deverá consultar diretamente o MCP. Ele trabalhará apenas com o resultado persistido do scanner.

## Etapa 10 — Plano e aplicação de edição

### Objetivo

Transformar decisões em operações verificáveis e aplicá-las com segurança.

### Implementar

- `GeradorDePlanoDeEdicao`;
- modelo de operação;
- validação do plano;
- `AplicadorDeOperacoes`;
- executor de comandos MCP;
- confirmação após cada operação;
- rollback ou estratégia de recuperação;
- modo de simulação;
- auditoria completa.

### Regra

Nenhuma escrita deverá ser liberada sem validação explícita do plano e confirmação do estado do Premiere.

## Ordem de prioridade

```text
Leitura completa da timeline
        ↓
Arquivos e metadados
        ↓
Áudio
        ↓
Transcrição
        ↓
Análise visual
        ↓
Cenas e eventos
        ↓
Retakes
        ↓
Persistência e retomada
        ↓
Motor de decisão
        ↓
Plano de edição
        ↓
Aplicação no Premiere
```

## Critério para avançar de etapa

Só avançaremos quando a etapa atual tiver:

- responsabilidade documentada;
- contratos definidos;
- implementação isolada;
- testes automatizados;
- integração simulada;
- tratamento de erros;
- logs adequados;
- validação contra o ambiente real, quando aplicável;
- nenhum acoplamento indevido com etapas futuras.

## Próximo plano imediato

O próximo incremento será a conclusão da leitura da timeline, com foco em:

1. separar os modelos de domínio em módulos próprios;
2. criar `ConversorDeFaixas`;
3. criar `ConversorDeClipes`;
4. adicionar validação estruturada;
5. salvar fixtures reais do MCP;
6. ampliar os testes;
7. executar novamente a leitura contra o Premiere.