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

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

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.