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

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

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.