gart/code/Engine/docs/06_BOAS_PRATICAS.md

06 — Boas Práticas de Programação (G-ART)

Escopo: Checklist de qualidade a aplicar antes de dar algo por pronto. Não cobre: Por onde começar uma tarefa (→ 09) · o que já quebrou (→ 05)

Propósito: registrar as melhores práticas de programação a serem aplicadas sempre que qualquer alteração ou correção for feita neste programa. Servem de checklist obrigatório antes de concluir qualquer mudança.

Regra: antes de considerar uma alteração concluída, confira os itens abaixo. Eles são o mesmo espírito do fluxo de validação pós-correção (Engine/run_after_fix.sh), mas cobrem também qualidade de código e convenções do projeto.

---

1. Correções de código

1. Sempre valide após corrigir — rode ./Engine/run_after_fix.sh (lint + testes). Nunca declare uma correção pronta sem que lint e a suíte passem.
2. Toda correção já corrigida vira registro — registre o problema em Engine/docs/05_EXPERIENCIAS.md para que não se repita.
3. Mude o mínimo necessário — altere apenas o que resolve o problema; evite refatorar código não relacionado na mesma mudança.

2. Tempo e FCPXML

4. Nunca use float para tempo — toda duração/offset é TimeValue (fração racional "600/2400s"). Float introduz erro de arredondamento.
5. offset é a posição na timeline; start é o in-point na origem — não confundir nas edições de clip.
6. Markers são filhos dos clips, não irmãos — e <spine> é a storyline primária; connected clips penduram-se com atributo lane.
7. Preserve sidecars em bundles .fcpxmld — ao gravar um bundle, copie os arquivos de dados; caso contrário destrói object-tracking/Cinematic.

3. Estrutura e arquitetura

8. Mantenha o núcleo desacoplado — fcpxml/ não conhece o protocolo MCP; server.py é a camada de transporte. Não vazem lógica MCP para o núcleo.
9. Use o padrão de dispatch — sem cadeias gigantes de if/elif; use TOOL_HANDLERS (dicionário nome → handler assíncrono).
10. Reaproveite os helpers centrais — _parse_project(), _resolve_io_paths(), _setup_modifier(), etc. Não duplique parse/validação de caminho.
11. Nunca sobrescreva o original — use generate_output_path() e crie _modified, _chapters, etc.
12. Mantenha o MarkerType como single source of truth — a serialização (parse/escrita) vive no enum, não espalhada por handlers.

4. Segurança

13. Sempre use safe_xml.py (defusedxml) — todos os entry points de parse; jamais xml.etree cru com input não confiável.
14. Valide caminhos com _validate_filepath / _validate_output_path — o sandbox de I/O existe para impedir escrita fora do permitido.
15. Rejeite payloads excessivamente aninhados — _check_json_depth protege contra payloads além de 50 níveis.
16. Nunca registre/commite segredos ou chaves — nem em logs, nem em código.

5. Qualidade e clareza

17. Sem comentários desnecessários — código deve ser autoexplicativo; comente o porquê, não o o quê.
18. Mimice as convenções do projeto — mesma estrutura de imports, nomes, padrões e bibliotecas já usadas nas vizinhas.
19. Lazy import de dependências opcionais — media_intel (librosa) e transcribe (Whisper) importam sob demanda e degradam com graça (None).
20. Convenções de teste — use examples/sample.fcpxml + fixtures XML inline; sample.fcpxml NÃO é DTD-conformante, não o use como fixture de validade DTD.

6. Checklist final antes de concluir uma alteração

• ./Engine/run_after_fix.sh passou (lint zero erros + todos os testes).
• Problema registrado em Engine/docs/05_EXPERIENCIAS.md (se aplicável).
• Nenhum float usado em matemática de tempo.
• Nenhum caminho original sobrescrito.
• safe_xml.py usado em todo parse de input não confiável.
• Nenhum segredo registrado ou commitado.
• Mudança mínima, sem refatoração não relacionada.
• Boa prática nova aprendida adicionada a esta lista.