João HenriqueandClaude Opus 5
711c397dfe
Ao dividir _shared.py em admin/api/*.py ontem, o cálculo `Path(__file__).resolve().parent.parent / "code"` foi copiado sem ajustar para o nível de diretório novo. No arquivo original (admin/models_api.py, direto em admin/) dois `.parent` chegavam na raiz do repo. Em admin/api/shared.py, um nível mais fundo, dois `.parent` param em admin/ — e admin/code nunca existiu. sys.path nunca recebia code/, então toda ação que passa por `server` (analisar voz, aplicar decisões) crashava o app com ModuleNotFoundError: server_tools. O bug sobreviveu a duas rodadas de validação da sessão anterior — lint zero, 1454 testes verdes, comando testado manualmente pela ponte — porque todos rodam num venv com install editável (__editable__.fcp_mcp_server.pth) que já deixa fcpxml/server_tools importáveis por conta própria, mascarando qualquer erro no cálculo manual de sys.path. Só o app real, no fallback sem uv, expõe o bug. Correção: o cálculo de sys.path sai de cada módulo de comando (estava duplicado em nove arquivos) e passa a existir uma única vez em admin/api/__init__.py, que roda antes de qualquer submódulo — nenhum precisa mais da própria cópia. O teste de regressão precisou de duas tentativas pelo mesmo motivo do bug: a primeira versão também passava com o bug presente, por rodar no mesmo venv "de sorte". Só ficou confiável isolando um subprocess que remove site-packages do sys.path antes de importar — confirmado nos dois sentidos, falha com o bug reintroduzido e passa com a correção (TestCodeDirResolution). Detalhe completo, incluindo por que o comando manual não pegou: Engine/docs/05_EXPERIENCIAS.md #25. Lint zerado, 1457 testes passando (3 novos), app compilado. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
158 lines
7.7 KiB
Markdown
158 lines
7.7 KiB
Markdown
# 09 — Manutenção: onde mexer, o que está aberto, o que dói
|
|
|
|
> **Escopo:** Por onde começar cada tipo de tarefa, o que está aberto e onde dói.
|
|
> **Não cobre:** Como as coisas funcionam — este doc roteia para quem explica
|
|
|
|
Este é o documento de rota. Os outros descrevem o que **é**; este diz o que
|
|
**fazer** e por onde começar quando chega uma implementação, uma melhoria ou
|
|
uma correção.
|
|
|
|
Última varredura: 2026-08-19 · 1.454 testes · lint zerado
|
|
|
|
---
|
|
|
|
## 1. Chegou uma tarefa — por onde começo?
|
|
|
|
| A tarefa é… | Comece em | Não esqueça |
|
|
|-------------|-----------|-------------|
|
|
| Regra nova de edição (corte, zoom, legenda) | `fcpxml/<módulo>` + teste | Expor na tool **e** na ponte, senão só metade dos usuários alcança |
|
|
| Corrigir XML que o FCP recusa | `fcpxml/writer/` + `dtd.py` | Validar contra o DTD real, não só o teste |
|
|
| Mudança visível na interface | `MacApp/Sources/` | **Abrir a tela** — compilar não prova nada (§4) |
|
|
| Comando novo para o app | `admin/api/<assunto>.py` | Registrar na tabela de `models_api.py` |
|
|
| Ferramenta MCP nova | `server_tools/<categoria>.py` | Schema `Tool(...)` + `TOOL_HANDLERS` |
|
|
| Ajuste de análise de voz | `fcpxml/voice_*`, `emphasis.py` | Regerar os `_voice_timeline.json` de teste |
|
|
| "Está lento" / "está errado" e não sei onde | §5 (mapa de sintomas) | — |
|
|
|
|
**A pergunta que resolve 90% das dúvidas de lugar:** essa lógica precisa saber
|
|
o que é uma tool MCP ou uma tela? Se não precisa — e quase nunca precisa — ela
|
|
vai para `fcpxml/`.
|
|
|
|
---
|
|
|
|
## 2. O que está aberto agora
|
|
|
|
Ordenado por quanto atrapalha, não por esforço.
|
|
|
|
### 2.1 A etapa 6 ignora a revisão de ênfases
|
|
O usuário lapida as frases na etapa 5, o `_phrase_review.json` é gravado — e a
|
|
etapa 6 ainda processa como antes. Falta ligar: **zoom e legenda dinâmica só
|
|
nas frases de ênfase, legenda comum no resto**. É a continuação natural do
|
|
trabalho da etapa 5 e o item mais valioso da lista.
|
|
→ `MacApp/Sources/WizardView.swift` (`finalizeProcessing`), `admin/api/subtitles.py`,
|
|
`fcpxml/phrase_review.py` (`emphasis_spans` já é produzido e ninguém consome).
|
|
|
|
### 2.2 Offset de ~400 ms no timing por palavra
|
|
O faster-whisper sem alinhamento forçado erra o início de cada palavra em
|
|
~0,4 s. Isso desloca zoom, corte e `gap_before` de uma vez. Há paliativo
|
|
aplicado por projeto; a correção estrutural é ligar o **WhisperX** (ou
|
|
alinhamento equivalente) em `transcribe.py`, o que levaria o erro para ~30 ms.
|
|
Custo real: regerar todos os `_transcript.json` e `_voice_timeline.json`
|
|
existentes. → `05_EXPERIENCIAS.md` #14, estado `parcialmente resolvido`.
|
|
|
|
### 2.3 `MacApp/` não tem teste automatizado
|
|
5.500 linhas de Swift sem uma asserção. A rede hoje é o harness manual (§4) e
|
|
o olho do usuário. Não é para sair criando suíte de UI — mas lógica pura que
|
|
foi parar na camada de tela (cálculo de trim, mapeamento de tempo) deveria
|
|
descer para o Python, onde já existe rede.
|
|
|
|
### 2.4 `admin/` fica fora do lint
|
|
`run_after_fix.sh` roda o ruff de dentro de `code/`, então `admin/` — 1.751
|
|
linhas de código que o app depende para funcionar — nunca é verificado.
|
|
Incluir mexe no gate, então é decisão consciente, não esquecimento.
|
|
|
|
### 2.5 Confirmações visuais pendentes no FCP
|
|
Várias entradas do `05_EXPERIENCIAS.md` estão marcadas como resolvidas *no XML*
|
|
— testes verdes, DTD válido — mas **pendentes de importação real no Final Cut**.
|
|
XML válido não é o mesmo que XML que renderiza como o esperado. Ao mexer em
|
|
legenda, zoom ou keyframe, a confirmação final é abrir no FCP.
|
|
|
|
### 2.6 Submódulo `WHISPERX` com conteúdo modificado e não commitado
|
|
Está fora dos commits de propósito, porque ninguém verificou o que mudou lá
|
|
dentro. Precisa ser olhado e resolvido — ou commitado, ou revertido.
|
|
|
|
---
|
|
|
|
## 3. Onde o código ainda é grande (e onde isso não é problema)
|
|
|
|
Quatro arquivos foram divididos (`writer.py`, `models.py`, `models_api.py`,
|
|
`_shared.py`): 6.685 linhas concentradas viraram 43 módulos.
|
|
|
|
O que sobrou grande, e o diagnóstico honesto de cada um:
|
|
|
|
| Arquivo | Linhas | Vale dividir? |
|
|
|---------|-------:|---------------|
|
|
| `fcpxml/text_layout.py` | 901 | **Não.** É diagramação — um assunto coeso. |
|
|
| `fcpxml/rough_cut.py` | 798 | **Não.** É geração de timeline, um assunto. |
|
|
| `fcpxml/model_manager.py` | 748 | Talvez: mistura catálogo, download e config. |
|
|
| `server_tools/voice.py` | 754 | Talvez, se crescer mais. |
|
|
| `MacApp/TranscriptionView.swift` | 843 | Sim, quando for mexer nela. |
|
|
| `MacApp/WizardView.swift` | 808 | Sim: sete etapas num `switch` só. |
|
|
|
|
**Critério, não número:** divida quando o arquivo tiver **assuntos** que não se
|
|
falam. Um arquivo grande de um assunto só é mais fácil de ler que seis arquivos
|
|
pequenos que você precisa abrir juntos. Código picado sem motivo atrapalha tanto
|
|
quanto arquivo gigante.
|
|
|
|
---
|
|
|
|
## 4. Checklist antes de dar algo por pronto
|
|
|
|
```bash
|
|
cd code && ./Engine/run_after_fix.sh # lint zerado + 1.454 testes
|
|
cd code && ./MacApp/build_app.sh --run # se mexeu no app
|
|
```
|
|
|
|
E, além do script:
|
|
|
|
- [ ] **Mexeu na interface? Abriu a tela?** Compilar não prova que roda —
|
|
`VideoPlayer` compilava e abortava (`05_EXPERIENCIAS.md` #22).
|
|
- [ ] **Mexeu em XML? Importou no FCP?** DTD válido ≠ renderiza certo.
|
|
- [ ] **Dividiu ou moveu módulo?** Procure `patch('<módulo>.` e imports
|
|
relativos dentro de funções — é o que quebra em silêncio (#23).
|
|
- [ ] **Criou teste fora de `code/tests/`?** Confirme que a contagem total
|
|
subiu. Teste fora de `testpaths` não roda e dá falsa sensação de rede (#24).
|
|
- [ ] **Problema estrutural ou erro recorrente?** Registre em
|
|
`05_EXPERIENCIAS.md` com o índice atualizado.
|
|
- [ ] **Documentação divergiu?** Corrija no mesmo commit. Doc velha engana mais
|
|
que doc ausente.
|
|
|
|
---
|
|
|
|
## 5. Mapa de sintomas → onde olhar
|
|
|
|
| Sintoma | Suspeite de | Arquivo |
|
|
|---------|-------------|---------|
|
|
| FCP recusa o arquivo ao importar | `id` inválido, ordem de filhos, timebase | `writer/validation.py`, `dtd.py` |
|
|
| Título importa mas não aparece | Template/uid Motion que não resolve | `writer/titles.py` |
|
|
| Corte no lugar errado | Tempo pós-corte usado como se fosse original | `voice_actions.py` (`shift_after_cuts`) |
|
|
| Zoom no lugar errado | Idem, ou offset de timing do Whisper | §2.2 |
|
|
| Legenda sobrepondo | Layout ou conteúdo antigo no arquivo | `collision.py`, `text_layout.py` |
|
|
| "Ênfase" apontando para palavra à toa | Falta renormalizar após o corte | `refine_voice_timeline` |
|
|
| App diz que falta librosa/pyannote | `uv run` com cwd errado | `PythonBridge.swift` (§3 do doc 08) |
|
|
| App crasha com `ModuleNotFoundError: server_tools` | `sys.path` de `admin/api/` mal calculado | `05_EXPERIENCIAS.md` #25 |
|
|
| Tela do app fecha o programa | Componente de framework que só falha em runtime | `05_EXPERIENCIAS.md` #22 |
|
|
| Comando existe no MCP mas não no app | Falta expor na ponte | `admin/api/`, #20 |
|
|
|
|
---
|
|
|
|
## 6. Convenções que não são negociáveis
|
|
|
|
Estão em `01_ARCHITECTURE.md` §2 e valem repetir as três que mais custaram:
|
|
|
|
1. **Tempo é fração racional.** Float para tempo produz drift que só aparece
|
|
depois de dez operações encadeadas.
|
|
2. **Ação de voz é sempre em tempo da mídia original.** Nunca pós-corte.
|
|
3. **Original nunca é sobrescrito.** Toda saída ganha sufixo.
|
|
|
|
---
|
|
|
|
## Documentos relacionados
|
|
|
|
- [01 Arquitetura](01_ARCHITECTURE.md) — camadas e onde cada coisa mora
|
|
- [02 Módulos](02_MODULES.md) — mapa do engine, módulo a módulo
|
|
- [03 Server/Tools](03_SERVER_TOOLS.md) — as 74 ferramentas MCP
|
|
- [04 Testes & Workflow](04_TESTS_AND_WORKFLOW.md)
|
|
- [05 Experiências](05_EXPERIENCIAS.md) — o que já quebrou e por quê
|
|
- [06 Boas Práticas](06_BOAS_PRATICAS.md)
|
|
- [08 App macOS](08_APP_MACOS.md) — o app e o Assistente
|