BirdNET-Uploader-App / SPRINT_ROADMAP.md
jrrribeiro's picture
Forçar atualização total do app
2f1a5fb
|
Raw History Blame Contribute Delete
19.6 kB
# BirdNET Uploader: Sprint Roadmap (MVP 6-8 semanas)
## Overview
**Objetivo**: Entregar executável local moderno, um fluxo integrado, pausa/retomada, compatibilidade com validador.
**Timeline**:
- **Semanas 1-2**: Arquitetura + Setup (Foundation)
- **Semanas 3-4**: Módulos Core (Auth, Repo, Upload)
- **Semanas 5-6**: UI + Session Manager (Integration)
- **Semanas 7-8**: Build + Testes + Release (Polish)
**Team**: 2-3 engineers (1 backend, 1 frontend/UI, 1 QA/DevOps)
---
## SPRINT 1: Foundation & Architecture (Semanas 1-2)
### Semana 1: Setup Inicial + Design Review
#### Task 1.1: Setup do Projeto (2 dias, 3 pts)
**Objetivo**: Estrutura base, dependências, CI/CD
**Tarefas**:
- [ ] Criar branch `feature/birdnet-uploader-cli`
- [ ] Criar estrutura de diretórios (`src/`, `tests/`, `build/`)
- [ ] Setup `pyproject.toml` e `requirements.txt`
- huggingface_hub>=0.28.0
- click>=8.0.0
- textual>=0.30.0 (TUI)
- rich>=13.0.0
- pydantic>=2.0.0
- pandas>=2.0.0
- pyarrow>=14.0.0
- keyring>=24.0.0
- [ ] Setup GitHub Actions para lint/test
- [ ] Criar `src/__init__.py` e `src/main.py` (skeleton)
**Critério de Pronto**:
- `pip install -r requirements.txt` sem erro
- `python -m src.main --help` roda e exibe help text
---
#### Task 1.2: Design Review + Arquitetura Finalizada (2 dias, 2 pts)
**Objetivo**: Alinhamento com stakeholders, decisões arquiteturais bloqueantes
**Tarefas**:
- [ ] Revisar documento REDESIGN com time
- [ ] Decisão final: Textual vs Rich+Click vs Typer (recomendação: Textual para melhor UX)
- [ ] Decidir sobre persistência: SQLite vs JSON files (recomendação: JSON + estrutura de diretórios)
- [ ] Validar estrutura de repositório HF (audio/index/validations/audit)
- [ ] Documentar todas as decisões em `docs/architecture-decisions.md`
**Critério de Pronto**:
- Documento de decisões assinado
- Time alinhado em tecnologia stack
- Nenhuma bloqueante técnica identificada
---
#### Task 1.3: Estrutura Base de Módulos (2 dias, 3 pts)
**Objetivo**: Criar interfaces/contracts de todos os módulos
**Tarefas**:
- [ ] Criar `src/auth/__init__.py` + `auth_service.py` (skeleton com docstrings)
- [ ] Criar `src/repository/__init__.py` + `repo_service.py` (skeleton)
- [ ] Criar `src/upload/__init__.py` + `scanner.py`, `uploader.py`, `deduplicator.py` (skeleton)
- [ ] Criar `src/csv/__init__.py` + `csv_matcher.py`, `indexer.py` (skeleton)
- [ ] Criar `src/session/__init__.py` + `session_manager.py`, `checkpoint.py` (skeleton)
- [ ] Criar `src/ui/__init__.py` + `tui.py`, `progress_renderer.py` (skeleton)
- [ ] Criar `src/logger/__init__.py` + `structured_logger.py` (skeleton)
- [ ] Criar `src/utils/__init__.py` + `file_utils.py`, `hash_utils.py`, `error_handler.py` (skeleton)
**Critério de Pronto**:
- Todos os módulos existem com `pass` ou docstrings
- Nenhum erro de import circular
- `python -c "import src; print('OK')"` funciona
---
#### Task 1.4: Testes Base + Test Fixtures (1 dia, 2 pts)
**Objetivo**: Infraestrutura de testes pronta
**Tarefas**:
- [ ] Setup `pytest.ini` e `conftest.py`
- [ ] Criar test fixtures para:
- Mock HfApi
- Pasta local temporária com arquivos de teste
- Session mock
- Token mock
- [ ] Criar `tests/test_auth.py` (skeleton)
- [ ] Criar `tests/test_uploader.py` (skeleton)
- [ ] Criar `tests/test_session.py` (skeleton)
**Critério de Pronto**:
- `pytest` executa sem erro (mesmo que tests sejam vazios)
- Fixtures estão disponíveis para todos os testes
---
### Semana 2: Auth + Repository Services
#### Task 2.1: Auth Service - Implementação Completa (2.5 dias, 5 pts)
**Objetivo**: Login com token, validação, armazenamento seguro
**Tarefas**:
- [ ] Implementar `AuthService.authenticate(token)`:
- Validar token contra HF API
- Recuperar info do usuário (username, email, user_id)
- Salvar em keyring (Windows DPAPI)
- Retornar user context
- [ ] Implementar `AuthService.get_stored_token()`:
- Recuperar token do keyring
- Lançar erro claro se não encontrado
- [ ] Implementar `AuthService.clear_token()`:
- Remover token do keyring
- [ ] Implementar `TokenManager`:
- Gerenciar TTL de token
- Detectar expiração
- Forçar re-autenticação se necessário
- [ ] Tests:
- [ ] `test_auth_valid_token()`
- [ ] `test_auth_invalid_token()`
- [ ] `test_auth_token_stored_in_keyring()`
- [ ] `test_auth_token_retrieval()`
**Critério de Pronto**:
- Todos os testes de auth passando
- Token nunca é logado/printed
- Falha de auth retorna mensagem clara
---
#### Task 2.2: Repository Service - Criar Dataset (2 dias, 4 pts)
**Objetivo**: Criar dataset HF e inicializar estrutura padrão
**Tarefas**:
- [ ] Implementar `RepositoryService.create_dataset()`:
- Validar nome do repositório (slug format)
- Criar dataset no HF (público/privado)
- Inicializar pastas padrão (audio/, index/shards/, validations/, audit/)
- Criar manifest.json inicial
- Retornar repo_id
- [ ] Implementar `RepositoryService.validate_repo()`:
- Verificar permissão de escrita
- Verificar estrutura esperada
- Retornar validation result
- [ ] Tests:
- [ ] `test_create_dataset_public()`
- [ ] `test_create_dataset_private()`
- [ ] `test_create_dataset_name_validation()`
- [ ] `test_validate_repo_structure()`
**Critério de Pronto**:
- Dataset criado no HF com structure correta
- Manifest.json com schema_version, project_slug, index
- Testes mockeados passando
---
#### Task 2.3: Config + Constants Finalizadas (1 dia, 2 pts)
**Objetivo**: Configuração centralizada do app
**Tarefas**:
- [ ] Criar `src/config.py`:
- `AUDIO_EXTENSIONS = ['.wav', '.mp3', '.flac', '.ogg']`
- `SESSION_DIR = ~/.birdnet-uploader/sessions/`
- `CACHE_DIR = ~/.birdnet-uploader/cache/`
- `MAX_BATCH_SIZE = 10`
- `RETRY_MAX_ATTEMPTS = 3`
- `RETRY_INITIAL_BACKOFF = 1.0`
- `MANIFEST_SCHEMA_VERSION = "1.0.0"`
- [ ] Implementar config via `.env` se necessário
**Critério de Pronto**:
- Todas as constantes centralizadas
- Nenhum hardcoded value em módulos
---
#### Task 2.4: Error Handling Framework (1.5 dias, 3 pts)
**Objetivo**: Exceções customizadas e mensagens claras
**Tarefas**:
- [ ] Criar `src/exceptions.py`:
- `AuthenticationError`
- `RepositoryError`
- `UploadError`
- `SessionError`
- `ValidationError`
- [ ] Implementar `src/utils/error_handler.py`:
- Converter exceções em mensagens user-friendly
- Log estruturado de erros
- Sugestões de ação
**Critério de Pronto**:
- Todas as exceções possuem mensagem clara
- Tests cobrem cenários de erro
---
## SPRINT 2: Upload & CSV Matching (Semanas 3-4)
### Semana 3: Scanner + File Operations
#### Task 3.1: Local Scanner - Varrer Pasta (2 dias, 4 pts)
**Objetivo**: Descobrir arquivos locais, agrupar por espécie
**Tarefas**:
- [ ] Implementar `LocalScanner.scan_folder()`:
- Varrer recursivamente
- Filtrar por extensões de áudio
- Inferir espécie do caminho/nome
- Calcular tamanho total e contagem
- Retornar estrutura normalizada
- [ ] Implementar estratégia de inferência de espécie:
- Strategy 1: Usar última pasta como specie
- Strategy 2: Usar prefixo do arquivo
- Strategy 3: Permitir mapeamento manual
- [ ] Tests:
- [ ] `test_scan_folder_empty()`
- [ ] `test_scan_folder_multiple_species()`
- [ ] `test_scan_folder_specie_inference()`
- [ ] `test_scan_folder_with_nested_dirs()`
**Critério de Pronto**:
- Escaneia pasta com 1000+ arquivos em <5 segundos
- Estrutura normalizada e validada
---
#### Task 3.2: Hash Utils + File Operations (1.5 dias, 3 pts)
**Objetivo**: Computação de hash segura, operações de arquivo
**Tarefas**:
- [ ] Implementar `compute_file_hash(path) -> str`:
- SHA256 eficiente (streaming para arquivos grandes)
- Cache local de hashes
- [ ] Implementar `verify_file_integrity(path, hash)`:
- Validar arquivo não corrompido
- [ ] Tests:
- [ ] `test_compute_hash_small_file()`
- [ ] `test_compute_hash_large_file()`
- [ ] `test_hash_consistency()`
**Critério de Pronto**:
- Hash de arquivo 1GB < 2 segundos
- Testes passando
---
#### Task 3.3: Deduplicator - Verificar Existência (2 dias, 3 pts)
**Objetivo**: Detectar arquivos já no destino
**Tarefas**:
- [ ] Implementar `Deduplicator.check_remote()`:
- Query HF API para verificar existência por caminho
- Comparar tamanho + hash opcional
- Retornar status (SKIP, UPLOAD, CONFLICT)
- [ ] Implementar dedup local cache (evitar queries repetidas)
- [ ] Tests:
- [ ] `test_check_remote_new_file()`
- [ ] `test_check_remote_existing_file()`
- [ ] `test_check_remote_conflict()`
**Critério de Pronto**:
- Dedup funciona sem re-query excessiva
- Cache valida corretamente
---
#### Task 3.4: Session + Checkpoint - State Persistence (2.5 dias, 5 pts)
**Objetivo**: Persistência atomática de estado para retomada
**Tarefas**:
- [ ] Implementar `SessionManager.create_session()`:
- Gerar session_id
- Criar diretório de sessão
- Inicializar metadata.json
- [ ] Implementar `CheckpointManager.save_checkpoint()`:
- Escrita atômica (temp + rename)
- Validação de JSON
- Flush para disco (fsync)
- [ ] Implementar `CheckpointManager.load_checkpoint()`:
- Recuperar último checkpoint
- Validação de integridade
- [ ] Implementar `SessionManager.mark_file_done()`:
- Atualizar manifest por arquivo
- [ ] Tests:
- [ ] `test_session_creation()`
- [ ] `test_checkpoint_atomic_write()`
- [ ] `test_checkpoint_recovery_after_crash()`
- [ ] `test_session_resume_same_id()`
**Critério de Pronto**:
- Checkpoint atomático garante consistência
- Recuperação de crash funciona
- Testes cobrem falha de escrita
---
### Semana 4: Upload Engine + CSV Matching
#### Task 4.1: Batch Uploader - Motor Principal (3 dias, 6 pts)
**Objetivo**: Upload resiliente com retry/dedup/pause
**Tarefas**:
- [ ] Implementar `BatchUploader.upload_files()`:
- Iterar sobre estrutura de arquivos
- Aplicar dedup check
- Upload com retry automático
- Atualizar checkpoint por lote
- Callback de progresso
- [ ] Implementar retry com exponential backoff:
- Backoff: 1s → 2s → 5s → 10s → 30s
- Tratamento de 429 (rate limit)
- Max 3 retries por padrão
- [ ] Implementar pause/resume:
- Signal SIGTERM/SIGINT
- Salvar state
- Resume com checkpoint
- [ ] Tests:
- [ ] `test_upload_batch_success()`
- [ ] `test_upload_with_retry()`
- [ ] `test_upload_skip_existing()`
- [ ] `test_upload_pause_resume()`
**Critério de Pronto**:
- Upload funciona end-to-end
- Retry logic testado
- Pause/resume funciona
---
#### Task 4.2: CSV Matcher + Index Generator (2.5 dias, 5 pts)
**Objetivo**: Matching CSV com segmentos e geração de índice
**Tarefas**:
- [ ] Implementar `CSVMatcher.match_detections()`:
- Ler CSV com validação de schema
- Fazer matching com segmentos (source_file → arquivo local)
- Gerar detection_key determinístico
- Retornar matched + unmatched + ambiguous
- [ ] Implementar `IndexGenerator.generate_shards()`:
- Particionar dados em shards (tamanho configurável)
- Salvar como parquet
- Gerar metadata de shards
- [ ] Implementar `ManifestBuilder.build()`:
- Construir manifest.json com schema_version
- Incluir metadados de index
- Serializar JSON
- [ ] Tests:
- [ ] `test_csv_matching_success()`
- [ ] `test_csv_missing_columns()`
- [ ] `test_shard_generation()`
- [ ] `test_manifest_format()`
**Critério de Pronto**:
- CSV+segmentos matchados corretamente
- Shards gerados com formato correto
- Manifest válido e legível
---
## SPRINT 3: UI + Integration (Semanas 5-6)
### Semana 5: UI TUI Implementation
#### Task 5.1: Textual TUI - Fluxo Principal (3 dias, 6 pts)
**Objetivo**: Interface TUI moderna para guiar usuário
**Tarefas**:
- [ ] Criar `src/ui/screens/login_screen.py`:
- Input para token HF
- Validação em tempo real
- Mensagens de erro claras
- [ ] Criar `src/ui/screens/config_screen.py`:
- Form com campos: repo name, visibility, segments path, csv path
- Verificação de pasta
- Validação de formato
- [ ] Criar `src/ui/screens/summary_screen.py`:
- Exibir configuração resumida
- Botão de confirmação
- [ ] Criar `src/ui/screens/upload_screen.py`:
- Barra de progresso principal
- Progresso por arquivo
- Arquivo atual
- Último evento
- Botões pause/cancel
- [ ] Implementar navegação entre screens
**Critério de Pronto**:
- Fluxo completo funcionando (login → config → summary → upload)
- Inputs validados
- Navegação intuitiva
---
#### Task 5.2: Progress Renderer (1.5 dias, 3 pts)
**Objetivo**: Visualização rich de progresso
**Tarefas**:
- [ ] Implementar progress bar customizada:
- Percentual + barra visual
- ETA com update em tempo real
- Arquivo atual
- Contadores (uploaded/pending/failed/skipped)
- [ ] Implementar event log:
- Últimos 10 eventos
- Código de status/cor por tipo
**Critério de Pronto**:
- Progress bar atualiza sem flicker
- ETA coerente
- Eventos visíveis
---
### Semana 6: Integration + Testes End-to-End
#### Task 6.1: Integration Testing + Mocks (2 dias, 4 pts)
**Objetivo**: Teste de fluxo completo (mockeado)
**Tarefas**:
- [ ] Criar `tests/test_integration.py`:
- Teste login + config + upload (mockeado)
- Teste pause/resume
- Teste com CSV
- [ ] Mockar HfApi completamente
- [ ] Rodar testes de carga (1000+ arquivos mockeados)
**Critério de Pronto**:
- Testes de integração passando
- Sem vazamento de recursos
---
#### Task 6.2: Real Integration Test (pequena escala) (2 dias, 4 pts)
**Objetivo**: Teste real com dataset HF de verdade
**Tarefas**:
- [ ] Criar dataset de teste no HF (alice/test-uploader-small)
- [ ] Teste com 100 arquivos reais (~500MB)
- [ ] Validar estrutura no HF pós-upload
- [ ] Validar manifest.json e shards
**Critério de Pronto**:
- Arquivos aparecem no HF
- Estrutura correta
- Manifest válido
---
## SPRINT 4: Build + Polish (Semanas 7-8)
### Semana 7: Build + Release
#### Task 7.1: PyInstaller Setup (2 dias, 4 pts)
**Objetivo**: Gerar executável portátil Windows
**Tarefas**:
- [ ] Criar `build/pyinstaller_config.spec`:
- One-file executable
- Hidden imports para textual, rich, pandas, pyarrow
- Resource bundling
- [ ] Criar `build/build.py` script
- [ ] Testar executável gerado localmente
- [ ] Validar tamanho (~100-150MB)
**Critério de Pronto**:
- Executável funciona sem Python instalado
- Tamanho razoável
- Sem erros de runtime
---
#### Task 7.2: Documentação + README (1.5 dias, 2 pts)
**Objetivo**: Docs para usuários finais
**Tarefas**:
- [ ] Criar README.md com:
- Quick start (download, run, autenticar)
- Screenshots
- Troubleshooting
- FAQ
- [ ] Criar INSTALLATION.md
- [ ] Criar USAGE.md (exemplos de comando)
**Critério de Pronto**:
- Usuário não-técnico consegue rodar pelo README
---
#### Task 7.3: Testes de Carga + Stress (2 dias, 4 pts)
**Objetivo**: Validar com dados reais maiores
**Tarefas**:
- [ ] Teste com pasta 5GB (1000+ arquivos)
- [ ] Teste com CSV 5000+ linhas
- [ ] Teste pause/resume 5x
- [ ] Monitorar memória e CPU
- [ ] Documentar performance (tempo/MB/s)
**Critério de Pronto**:
- Memória < 500MB durante upload
- CPU < 30% média
- Upload rate > 5 MB/s (com rede OK)
---
### Semana 8: Release + Smoke Tests
#### Task 8.1: Release Pipeline (1.5 dias, 2 pts)
**Objetivo**: Setup de distribuição
**Tarefas**:
- [ ] Criar release no GitHub com:
- Executável (`.exe`)
- SHA256 hash
- Release notes
- Link para docs
- [ ] Testar download + execução do exe
- [ ] Validar assinatura (opcional nesta fase)
**Critério de Pronto**:
- Release publicado
- Download funciona
- Exe roda após download/extração
---
#### Task 8.2: Smoke Tests + Final QA (1.5 dias, 3 pts)
**Objetivo**: Validação final antes do release
**Tarefas**:
- [ ] Checklist final:
- [ ] Login funciona
- [ ] Criar repo funciona
- [ ] Upload de 10GB completa
- [ ] Pause/resume sem perda
- [ ] CSV matching correto
- [ ] Manifest válido no destino
- [ ] Estrutura compatível com validador
- [ ] Teste com 3+ usuários externos (team)
- [ ] Coleta de feedback
**Critério de Pronto**:
- Zero bugs críticos
- Feedback incorporado
- Pronto para release
---
## BACKLOG: Priorização de Tasks
| Sprint | Semana | Task | Pts | Status |
|--------|--------|------|-----|--------|
| 1 | 1 | Setup + Design | 5 | Não iniciado |
| 1 | 1 | Arquitetura de Módulos | 3 | Não iniciado |
| 1 | 1 | Test Infrastructure | 2 | Não iniciado |
| 1 | 2 | Auth Service | 5 | Bloqueado por 1.1 |
| 1 | 2 | Repository Service | 4 | Bloqueado por 1.1 |
| 1 | 2 | Config + Constants | 2 | Bloqueado por 1.1 |
| 1 | 2 | Error Handling | 3 | Bloqueado por 1.1 |
| 2 | 3 | Local Scanner | 4 | Bloqueado por Sprint 1 |
| 2 | 3 | Hash Utils | 3 | Bloqueado por Sprint 1 |
| 2 | 3 | Deduplicator | 3 | Bloqueado por Sprint 1 |
| 2 | 3 | Session + Checkpoint | 5 | Bloqueado por Sprint 1 |
| 2 | 4 | Batch Uploader | 6 | Bloqueado por Sprint 1 |
| 2 | 4 | CSV Matcher | 5 | Bloqueado por Sprint 1 |
| 3 | 5 | Textual TUI | 6 | Bloqueado por Sprint 2 |
| 3 | 5 | Progress Renderer | 3 | Bloqueado por Sprint 2 |
| 3 | 6 | Integration Tests | 4 | Bloqueado por Sprint 2 |
| 3 | 6 | Real Integration Test | 4 | Bloqueado por Sprint 2 |
| 4 | 7 | PyInstaller | 4 | Bloqueado por Sprint 3 |
| 4 | 7 | Documentation | 2 | Bloqueado por Sprint 3 |
| 4 | 7 | Load Testing | 4 | Bloqueado por Sprint 3 |
| 4 | 8 | Release Pipeline | 2 | Bloqueado por Sprint 3 |
| 4 | 8 | Final QA | 3 | Bloqueado por Sprint 3 |
**Total: ~84 story points (6-8 semanas com 2-3 eng)**
---
## Velocity + Alocação de Equipe
### Cenário 1: Full Team (2 eng)
- Sprint de 2 semanas, 2 eng = ~40 pts/sprint
- Sprint 1-2: 26 pts (semana 1 paralelo, semana 2 paralelo) ✓ cabe
- Sprint 2 continuation: ~20 pts (cabe)
- Sprint 3: ~13 pts (cabe)
- Sprint 4: ~15 pts (cabe)
### Cenário 2: 3 Eng (Backend + Frontend + QA)
- Paralelizar mais agressivamente
- Timeline pode reduzir de 8 para 6-7 semanas
---
## Critérios de "Done" por Sprint
### Sprint 1 Done ✓
- [ ] Todos os módulos base existem (importáveis)
- [ ] Auth funciona com keyring
- [ ] Repo pode ser criado no HF
- [ ] Testes de auth e repo passando
- [ ] Setup pronto para Sprint 2
### Sprint 2 Done ✓
- [ ] Scanner varre pasta corretamente
- [ ] Uploader faz batch com retry
- [ ] CSV matcher funciona end-to-end
- [ ] Checkpoint salva e recupera estado
- [ ] Testes cobrem 80%+ de lógica
### Sprint 3 Done ✓
- [ ] Fluxo TUI completo (login → config → upload)
- [ ] Progresso visual atualiza sem flicker
- [ ] Integração completa mockeada testada
- [ ] Real integration test com 500MB+ passou
- [ ] Pronto para build
### Sprint 4 Done ✓
- [ ] Executável portátil gerado e testado
- [ ] Release pipeline setup
- [ ] Documentação completa
- [ ] Smoke tests passando
- [ ] Pronto para distribuição
---
## Next Steps
1. **Aprovação**: Confirmar timeline, team size, prioridades
2. **Sprint 1 Kickoff**: Semana que vem
3. **Daily Standups**: 15min todo dia weekday
4. **Sprint Reviews**: Sexta-feira cada semana
5. **Retrospectives**: Fim de cada sprint
---
## Notas & Riscos
- **Risco 1**: PyInstaller não empacotar corretamente → Mitigar: spike de 1 dia em week 7
- **Risco 2**: Performance ruim em 50GB+ → Mitigar: load test cedo (week 4)
- **Risco 3**: Incompatibilidade com validador → Mitigar: validação de manifest early (week 4)
- **Risco 4**: UX TUI confusa → Mitigar: user testing em week 6
Todas as risks têm mitigation strategy atrelada.