balantrapu87/amds

Manual de Execução SDLC do Motion Studio

Quando encarregado de implementar um recurso ou correção de bug neste repositório, execute exatamente estes passos em ordem:

Passo 1: Sincronização de Contratos (Portão de Especificação)

1. Inspecione engine/schemas.py e remotion/src/types.ts.
2. Adicione ou modifique campos para atender aos requisitos do recurso.
3. Valide que os modelos Pydantic compilam:

   python3 -c "import engine.schemas as s; print('Schemas OK')"
   

   (Nota: Se existir um virtualenv do projeto, invoque via .venv/bin/python3).
4. Nunca prossiga para o código de implementação até que os contratos em ambas as linguagens estejam alinhados.

Passo 2: Fase Vermelha (Autor Testes com Falha)

1. Escreva um novo arquivo de teste ou caso de teste em tests/ (Pytest) ou remotion/src/__tests__/ (Vitest/Jest).
2. Teste validação de schema, casos extremos e saída serializada esperada.
3. Execute o teste e confirme a falha:

   pytest tests/
   # Se o executor de testes frontend estiver configurado em remotion/package.json:
   npm --prefix remotion test -- --run
   

4. Registre o trace de falha. Se o teste for aprovado imediatamente, reescreva-o para testar a nova capacidade real. A fase Vermelha é satisfeita apenas quando os testes falham com as asserções esperadas.

Passo 3: Fase Verde (Implementação Mínima)

1. Escreva o código mínimo em engine/ ou remotion/src/ para satisfazer o teste com falha.
2. No Remotion, siga rigorosamente a Lei do Frame Determinístico:
   • A derivação deve vir estritamente de useCurrentFrame() e useVideoConfig().
   • Nunca use Date.now(), Math.random() ou requestAnimationFrame() sem limite.
3. Preserve os padrões arquiteturais existentes (<Series>, <Sequence>, <ThreeScene>, <KineticScene>).
4. Garanta que os assets vetoriais preservem IDs e classes conforme remotion/svgo.config.mjs para direcionamento GSAP.

Passo 4: Portão de Qualidade e Loop de Autocorreção Automatizada

Acompanhe o contador de iterações do loop (ATTEMPT ∈ {1, 2, 3}). Execute cada portão sequencialmente sem mascarar códigos de saída (não anexe || true):

# Nível 1: Análise Estática de Tipos
python3 -m mypy engine/schemas.py engine/api.py
npm --prefix remotion run build -- --bundle-cache=false

# Nível 2: Conjuntos de Testes Automatizados
pytest tests/
# Se o executor de testes frontend estiver configurado em remotion/package.json:
npm --prefix remotion test -- --run

# Nível 3: Rasterização de Frame com Chromium Headless
(cd remotion && npx remotion still src/index.ts MainComposition /tmp/smoke.png \
  --props='{"scenes":[],"theme":{}}' \
  --gl=angle \
  --overwrite)

Política de Autocorreção e Reversão

• Em caso de Falha (Tentativa 1 ou 2):

  1. Capture o caminho exato do arquivo, número da linha com falha e stderr/traceback.
  2. Implemente um patch mínimo e direcionado, tratando estritamente o erro relatado.
  3. Incremente ATTEMPT e reinicie o Nível 1.

• Em caso de Falha (Tentativa 3 - Orçamento Esgotado): Interrompa modificações especulativas imediatamente e reverta apenas os arquivos de recurso alterados e criados (nunca realize uma limpeza global geral):

  # Plano B de Exaustão do Nível 4: Direcionar apenas escopos de código do recurso
  git restore --staged --worktree engine/ remotion/ tests/
  git clean -fd engine/ remotion/ tests/
  rm -f /tmp/smoke.png
  echo "Portão de qualidade falhou após 3 tentativas. Caminhos de código alvo restaurados ao baseline limpo."
  exit 1
  

  (Alternativa para preservar trabalho para análise post-mortem: git stash push -u -m "sdlc-failed-attempt-$(date +%s)" -- engine/ remotion/ tests/)

• Em caso de Sucesso (Todos os Níveis Saem com 0): Remova artefatos transitórios e crie o commit verificado:

  rm -f /tmp/smoke.png
  git add engine/ remotion/ tests/
  git commit -m "feat(motion-sdlc): implement verified feature with green test gate"