Spaces:
Sleeping
Sleeping
Commit ·
8582d7f
1
Parent(s): 0bfe6f1
docs: add HF backlog and GitHub issues checklist
Browse files- GITHUB_ISSUES_HF_VALIDATOR.md +312 -0
- HUGGINGFACE_VALIDATOR_BACKLOG.md +244 -0
GITHUB_ISSUES_HF_VALIDATOR.md
ADDED
|
@@ -0,0 +1,312 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# GitHub Issues - BirdNET Validator HF
|
| 2 |
+
|
| 3 |
+
Use este arquivo como roteiro para abrir as issues no novo repositorio do app.
|
| 4 |
+
Sugestao: criar milestones por sprint e labels por tipo.
|
| 5 |
+
|
| 6 |
+
## Labels sugeridas
|
| 7 |
+
- epic
|
| 8 |
+
- p0
|
| 9 |
+
- p1
|
| 10 |
+
- backend
|
| 11 |
+
- frontend
|
| 12 |
+
- infra
|
| 13 |
+
- data
|
| 14 |
+
- auth
|
| 15 |
+
- performance
|
| 16 |
+
- testing
|
| 17 |
+
|
| 18 |
+
## Milestones sugeridas
|
| 19 |
+
- Sprint 0 - Preparacao
|
| 20 |
+
- Sprint 1 - Ingestao e indice
|
| 21 |
+
- Sprint 2 - Core leitura e cache
|
| 22 |
+
- Sprint 3 - Persistencia colaborativa
|
| 23 |
+
- Sprint 4 - Seguranca multi-projeto
|
| 24 |
+
- Sprint 5 - UX e performance
|
| 25 |
+
- Sprint 6 - Operacao e qualidade
|
| 26 |
+
|
| 27 |
+
## Issue 01 - Bootstrap do repositorio e CI minima
|
| 28 |
+
Title: [Sprint 0][P0] Bootstrap do repositorio birdnet-validator-hf-app
|
| 29 |
+
Labels: epic, p0, infra
|
| 30 |
+
Milestone: Sprint 0 - Preparacao
|
| 31 |
+
Body:
|
| 32 |
+
- Objetivo: inicializar o novo repositorio com estrutura base, lint, testes e pipeline minima.
|
| 33 |
+
- Tarefas:
|
| 34 |
+
- Criar estrutura src, tests, docs, cli.
|
| 35 |
+
- Adicionar pyproject.toml e requirements.
|
| 36 |
+
- Adicionar pre-commit (opcional) e GitHub Actions para teste.
|
| 37 |
+
- Subir app Gradio minimo com tela placeholder.
|
| 38 |
+
- Criterios de aceite:
|
| 39 |
+
- Repo roda local sem erro.
|
| 40 |
+
- CI executa em PR.
|
| 41 |
+
- README inicial com setup local.
|
| 42 |
+
|
| 43 |
+
## Issue 02 - Modelos de dominio e validacao de schema
|
| 44 |
+
Title: [Sprint 0][P0] Definir modelos de dominio e schema
|
| 45 |
+
Labels: p0, backend, data
|
| 46 |
+
Milestone: Sprint 0 - Preparacao
|
| 47 |
+
Body:
|
| 48 |
+
- Objetivo: criar modelos Project, Detection, Validation, User, Role, IndexManifest.
|
| 49 |
+
- Tarefas:
|
| 50 |
+
- Implementar modelos com dataclass/pydantic.
|
| 51 |
+
- Incluir validacoes de campos obrigatorios.
|
| 52 |
+
- Fixar versao do schema para evolucao futura.
|
| 53 |
+
- Criterios de aceite:
|
| 54 |
+
- Testes unitarios de validacao passam.
|
| 55 |
+
- Modelos serializam/deserializam sem perda.
|
| 56 |
+
|
| 57 |
+
## Issue 03 - Contratos de repositorio e fake adapters
|
| 58 |
+
Title: [Sprint 0][P0] Criar contratos de repositorio e adapters fake
|
| 59 |
+
Labels: p0, backend
|
| 60 |
+
Milestone: Sprint 0 - Preparacao
|
| 61 |
+
Body:
|
| 62 |
+
- Objetivo: desacoplar UI da persistencia desde o inicio.
|
| 63 |
+
- Tarefas:
|
| 64 |
+
- Definir interfaces: ProjectRepository, DetectionRepository, ValidationRepository, AuthRepository.
|
| 65 |
+
- Implementar adapters fake para testes locais.
|
| 66 |
+
- Criterios de aceite:
|
| 67 |
+
- Casos basicos funcionam sem HF remoto.
|
| 68 |
+
- Cobertura minima dos contratos.
|
| 69 |
+
|
| 70 |
+
## Issue 04 - CLI create-project para dataset HF
|
| 71 |
+
Title: [Sprint 1][P0] Implementar comando create-project
|
| 72 |
+
Labels: p0, backend, data
|
| 73 |
+
Milestone: Sprint 1 - Ingestao e indice
|
| 74 |
+
Body:
|
| 75 |
+
- Objetivo: criar estrutura do dataset por projeto no Hugging Face.
|
| 76 |
+
- Tarefas:
|
| 77 |
+
- Criar comando create-project.
|
| 78 |
+
- Estrutura inicial: audio, index, validations, audit, manifest.json.
|
| 79 |
+
- Criterios de aceite:
|
| 80 |
+
- Estrutura criada corretamente em dataset novo.
|
| 81 |
+
- Comando idempotente quando projeto ja existe.
|
| 82 |
+
|
| 83 |
+
## Issue 05 - CLI sync-audio com resume e retry
|
| 84 |
+
Title: [Sprint 1][P0] Upload de audio em lotes com resume idempotente
|
| 85 |
+
Labels: p0, backend, data, performance
|
| 86 |
+
Milestone: Sprint 1 - Ingestao e indice
|
| 87 |
+
Body:
|
| 88 |
+
- Objetivo: subir audios sem depender de fluxo Git LFS local.
|
| 89 |
+
- Tarefas:
|
| 90 |
+
- Implementar sync-audio em lotes.
|
| 91 |
+
- Retry com backoff e resume por checkpoint.
|
| 92 |
+
- Log transacional por lote.
|
| 93 |
+
- Criterios de aceite:
|
| 94 |
+
- Falha de rede nao duplica uploads.
|
| 95 |
+
- Retomada completa apos interrupcao.
|
| 96 |
+
|
| 97 |
+
## Issue 06 - CLI build-index e checksums
|
| 98 |
+
Title: [Sprint 1][P0] Gerar index_manifest e shards de deteccao
|
| 99 |
+
Labels: p0, data, backend
|
| 100 |
+
Milestone: Sprint 1 - Ingestao e indice
|
| 101 |
+
Body:
|
| 102 |
+
- Objetivo: permitir leitura paginada rapida no app.
|
| 103 |
+
- Tarefas:
|
| 104 |
+
- Gerar manifest.json com estatisticas.
|
| 105 |
+
- Gerar shards de deteccoes e checksums.
|
| 106 |
+
- Criterios de aceite:
|
| 107 |
+
- Manifesto referencia apenas artefatos existentes.
|
| 108 |
+
- Validacao de integridade passa.
|
| 109 |
+
|
| 110 |
+
## Issue 07 - CLI verify-project
|
| 111 |
+
Title: [Sprint 1][P0] Verificador de consistencia do projeto
|
| 112 |
+
Labels: p0, data, testing
|
| 113 |
+
Milestone: Sprint 1 - Ingestao e indice
|
| 114 |
+
Body:
|
| 115 |
+
- Objetivo: validar consistencia audio x index x deteccoes.
|
| 116 |
+
- Tarefas:
|
| 117 |
+
- Implementar comando verify-project.
|
| 118 |
+
- Emitir relatorio com erros e warnings.
|
| 119 |
+
- Criterios de aceite:
|
| 120 |
+
- Retorna codigo de erro em inconsistencias.
|
| 121 |
+
|
| 122 |
+
## Issue 08 - Fila paginada de deteccoes
|
| 123 |
+
Title: [Sprint 2][P0] Implementar detection queue paginada
|
| 124 |
+
Labels: p0, backend, performance
|
| 125 |
+
Milestone: Sprint 2 - Core leitura e cache
|
| 126 |
+
Body:
|
| 127 |
+
- Objetivo: navegar grandes volumes sem travar UI.
|
| 128 |
+
- Tarefas:
|
| 129 |
+
- API interna de pagina com filtros.
|
| 130 |
+
- Ordenacao estavel e cursor/offset.
|
| 131 |
+
- Criterios de aceite:
|
| 132 |
+
- Navega 50k deteccoes com fluidez.
|
| 133 |
+
|
| 134 |
+
## Issue 09 - Download sob demanda por audio_id
|
| 135 |
+
Title: [Sprint 2][P0] AudioFetchService para arquivo individual
|
| 136 |
+
Labels: p0, backend, performance
|
| 137 |
+
Milestone: Sprint 2 - Core leitura e cache
|
| 138 |
+
Body:
|
| 139 |
+
- Objetivo: baixar somente audio da deteccao ativa.
|
| 140 |
+
- Tarefas:
|
| 141 |
+
- Implementar fetch por audio_id.
|
| 142 |
+
- Tratamento de erro e retry curto.
|
| 143 |
+
- Criterios de aceite:
|
| 144 |
+
- Nenhum preload global do dataset.
|
| 145 |
+
|
| 146 |
+
## Issue 10 - Cache efemero e cleanup apos validacao
|
| 147 |
+
Title: [Sprint 2][P0] Implementar cache LRU TTL e limpeza pos-validacao
|
| 148 |
+
Labels: p0, backend, performance
|
| 149 |
+
Milestone: Sprint 2 - Core leitura e cache
|
| 150 |
+
Body:
|
| 151 |
+
- Objetivo: reduzir custo e memoria mantendo comportamento seguro.
|
| 152 |
+
- Tarefas:
|
| 153 |
+
- Cache em RAM e /tmp com limite configuravel.
|
| 154 |
+
- Cleanup apos salvar validacao.
|
| 155 |
+
- Criterios de aceite:
|
| 156 |
+
- Temporario removido apos validacao.
|
| 157 |
+
- Arquivo remoto permanece intacto.
|
| 158 |
+
|
| 159 |
+
## Issue 11 - Persistencia append-only de validacoes
|
| 160 |
+
Title: [Sprint 3][P0] Log append-only de eventos de validacao
|
| 161 |
+
Labels: p0, backend, data
|
| 162 |
+
Milestone: Sprint 3 - Persistencia colaborativa
|
| 163 |
+
Body:
|
| 164 |
+
- Objetivo: garantir trilha auditavel completa.
|
| 165 |
+
- Tarefas:
|
| 166 |
+
- Salvar eventos em shards por data.
|
| 167 |
+
- Incluir usuario, status anterior/novo, timestamp, notas.
|
| 168 |
+
- Criterios de aceite:
|
| 169 |
+
- Toda alteracao gera evento auditavel.
|
| 170 |
+
|
| 171 |
+
## Issue 12 - Snapshot current por detection_key
|
| 172 |
+
Title: [Sprint 3][P0] Materializar estado atual de validacoes
|
| 173 |
+
Labels: p0, backend, data, performance
|
| 174 |
+
Milestone: Sprint 3 - Persistencia colaborativa
|
| 175 |
+
Body:
|
| 176 |
+
- Objetivo: acelerar leitura do estado mais recente.
|
| 177 |
+
- Tarefas:
|
| 178 |
+
- Consolidar eventos em current.parquet.
|
| 179 |
+
- Criterios de aceite:
|
| 180 |
+
- Lookup por detection_key em baixa latencia.
|
| 181 |
+
|
| 182 |
+
## Issue 13 - Concorrencia otimista e merge de conflito
|
| 183 |
+
Title: [Sprint 3][P0] Controle de concorrencia para validadores simultaneos
|
| 184 |
+
Labels: p0, backend
|
| 185 |
+
Milestone: Sprint 3 - Persistencia colaborativa
|
| 186 |
+
Body:
|
| 187 |
+
- Objetivo: evitar perda silenciosa de dados.
|
| 188 |
+
- Tarefas:
|
| 189 |
+
- Implementar revisao/etag.
|
| 190 |
+
- Definir merge deterministico de conflitos.
|
| 191 |
+
- Criterios de aceite:
|
| 192 |
+
- Nao ha perda de validacao em concorrencia.
|
| 193 |
+
|
| 194 |
+
## Issue 14 - Login e sessao com papeis
|
| 195 |
+
Title: [Sprint 4][P0] AuthService com usuarios e papeis
|
| 196 |
+
Labels: p0, auth, backend
|
| 197 |
+
Milestone: Sprint 4 - Seguranca multi-projeto
|
| 198 |
+
Body:
|
| 199 |
+
- Objetivo: controlar acesso ao app e por projeto.
|
| 200 |
+
- Tarefas:
|
| 201 |
+
- Login e sessao segura.
|
| 202 |
+
- Papel admin e validator.
|
| 203 |
+
- Criterios de aceite:
|
| 204 |
+
- Usuario sem permissao nao acessa projeto indevido.
|
| 205 |
+
|
| 206 |
+
## Issue 15 - ACL por projeto
|
| 207 |
+
Title: [Sprint 4][P0] Isolamento de acesso por projeto
|
| 208 |
+
Labels: p0, auth, backend
|
| 209 |
+
Milestone: Sprint 4 - Seguranca multi-projeto
|
| 210 |
+
Body:
|
| 211 |
+
- Objetivo: evitar vazamento entre projetos.
|
| 212 |
+
- Tarefas:
|
| 213 |
+
- Enforcar filtro por projeto em todas consultas.
|
| 214 |
+
- Criterios de aceite:
|
| 215 |
+
- Dados de um projeto nao aparecem em outro.
|
| 216 |
+
|
| 217 |
+
## Issue 16 - Painel Admin multi-projeto
|
| 218 |
+
Title: [Sprint 4][P0] UI admin para projetos e membros
|
| 219 |
+
Labels: p0, frontend, auth
|
| 220 |
+
Milestone: Sprint 4 - Seguranca multi-projeto
|
| 221 |
+
Body:
|
| 222 |
+
- Objetivo: operar ambiente sem editar codigo.
|
| 223 |
+
- Tarefas:
|
| 224 |
+
- Criar/arquivar projeto.
|
| 225 |
+
- Atribuir usuarios por projeto.
|
| 226 |
+
- Mostrar progresso por projeto.
|
| 227 |
+
- Criterios de aceite:
|
| 228 |
+
- Alteracoes ficam disponiveis para novas sessoes.
|
| 229 |
+
|
| 230 |
+
## Issue 17 - Fluxo rapido de validacao
|
| 231 |
+
Title: [Sprint 5][P1] Acoes rapidas com auto-avanco
|
| 232 |
+
Labels: p1, frontend
|
| 233 |
+
Milestone: Sprint 5 - UX e performance
|
| 234 |
+
Body:
|
| 235 |
+
- Objetivo: aumentar throughput humano.
|
| 236 |
+
- Tarefas:
|
| 237 |
+
- Positivo/Negativo/Indeterminado/Pular com 1 clique.
|
| 238 |
+
- Criterios de aceite:
|
| 239 |
+
- Apos salvar, app avanca automaticamente.
|
| 240 |
+
|
| 241 |
+
## Issue 18 - Filtros compostos
|
| 242 |
+
Title: [Sprint 5][P1] Filtros por especie confianca status localidade data
|
| 243 |
+
Labels: p1, frontend, backend
|
| 244 |
+
Milestone: Sprint 5 - UX e performance
|
| 245 |
+
Body:
|
| 246 |
+
- Objetivo: melhorar foco de validacao.
|
| 247 |
+
- Criterios de aceite:
|
| 248 |
+
- Combinacao de filtros retorna resultados corretos.
|
| 249 |
+
|
| 250 |
+
## Issue 19 - Recuperacao de sessao
|
| 251 |
+
Title: [Sprint 5][P1] Restaurar ultimo contexto do usuario
|
| 252 |
+
Labels: p1, frontend
|
| 253 |
+
Milestone: Sprint 5 - UX e performance
|
| 254 |
+
Body:
|
| 255 |
+
- Objetivo: evitar perda de contexto ao recarregar.
|
| 256 |
+
- Criterios de aceite:
|
| 257 |
+
- Ultimo item e filtros principais restaurados.
|
| 258 |
+
|
| 259 |
+
## Issue 20 - Prefetch curto de audio
|
| 260 |
+
Title: [Sprint 5][P1] Prefetch de N proximos audios
|
| 261 |
+
Labels: p1, performance, backend
|
| 262 |
+
Milestone: Sprint 5 - UX e performance
|
| 263 |
+
Body:
|
| 264 |
+
- Objetivo: reduzir latencia do proximo item.
|
| 265 |
+
- Criterios de aceite:
|
| 266 |
+
- Melhora p95 sem extrapolar limite de cache.
|
| 267 |
+
|
| 268 |
+
## Issue 21 - Logs estruturados
|
| 269 |
+
Title: [Sprint 6][P1] Logging estruturado com correlacao
|
| 270 |
+
Labels: p1, infra
|
| 271 |
+
Milestone: Sprint 6 - Operacao e qualidade
|
| 272 |
+
Body:
|
| 273 |
+
- Objetivo: facilitar observabilidade e suporte.
|
| 274 |
+
- Criterios de aceite:
|
| 275 |
+
- Erros rastreaveis por usuario/projeto/request.
|
| 276 |
+
|
| 277 |
+
## Issue 22 - Metricas e painel operacional
|
| 278 |
+
Title: [Sprint 6][P1] Metricas de latencia erro throughput
|
| 279 |
+
Labels: p1, performance, frontend
|
| 280 |
+
Milestone: Sprint 6 - Operacao e qualidade
|
| 281 |
+
Body:
|
| 282 |
+
- Objetivo: monitorar saude do sistema em producao.
|
| 283 |
+
- Criterios de aceite:
|
| 284 |
+
- p50/p95 e taxa de erro visiveis no admin.
|
| 285 |
+
|
| 286 |
+
## Issue 23 - Testes de integracao e carga basica
|
| 287 |
+
Title: [Sprint 6][P1] Suite minima de qualidade para release
|
| 288 |
+
Labels: p1, testing
|
| 289 |
+
Milestone: Sprint 6 - Operacao e qualidade
|
| 290 |
+
Body:
|
| 291 |
+
- Objetivo: reduzir regressao antes de producao.
|
| 292 |
+
- Criterios de aceite:
|
| 293 |
+
- CI verde com testes unitarios e integracao.
|
| 294 |
+
|
| 295 |
+
## Dependencias recomendadas entre issues
|
| 296 |
+
- 01 -> 02 -> 03
|
| 297 |
+
- 03 -> 08, 09, 10, 11, 14
|
| 298 |
+
- 04, 05, 06 -> 07
|
| 299 |
+
- 06, 08 -> 09
|
| 300 |
+
- 09 -> 10 -> 20
|
| 301 |
+
- 11 -> 12 -> 13
|
| 302 |
+
- 14 -> 15 -> 16
|
| 303 |
+
- 08, 12, 14, 15 -> 17, 18, 19
|
| 304 |
+
- Todas P0 -> 21, 22, 23
|
| 305 |
+
|
| 306 |
+
## Checklist de fechamento da v1
|
| 307 |
+
- [ ] Upload CLI funcional para projetos grandes
|
| 308 |
+
- [ ] Index paginado publicado por projeto
|
| 309 |
+
- [ ] Audio sob demanda com cleanup local
|
| 310 |
+
- [ ] Validacao colaborativa com auditoria
|
| 311 |
+
- [ ] ACL por projeto e painel admin
|
| 312 |
+
- [ ] Metricas e testes minimos em CI
|
HUGGINGFACE_VALIDATOR_BACKLOG.md
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# BirdNET Validator HF - Backlog Executavel
|
| 2 |
+
|
| 3 |
+
## 1) Objetivo
|
| 4 |
+
Construir um novo app de validacao de deteccoes BirdNET para Hugging Face Spaces (Gradio), reutilizavel para varios projetos, com:
|
| 5 |
+
- Um dataset Hugging Face por projeto
|
| 6 |
+
- Download de audio sob demanda (1 arquivo por vez)
|
| 7 |
+
- Limpeza de memoria/temporario apos validacao
|
| 8 |
+
- Sem remover arquivos no dataset remoto
|
| 9 |
+
- Upload de dados via CLI usando API (`huggingface_hub`), sem fluxo Git LFS local
|
| 10 |
+
- Gestao de usuarios/papeis e isolamento por projeto
|
| 11 |
+
|
| 12 |
+
## 2) Estrategia de repositorios
|
| 13 |
+
### Repositorio 1 (novo): app
|
| 14 |
+
- Nome sugerido: `birdnet-validator-hf-app`
|
| 15 |
+
- Conteudo: Gradio app, servicos, auth, cache, UI, testes, docs de deploy
|
| 16 |
+
|
| 17 |
+
### Repositorios 2..N: datasets por projeto
|
| 18 |
+
- Nome sugerido: `birdnet-<project-slug>-dataset`
|
| 19 |
+
- Conteudo: `audio/`, `index/`, `validations/`, `audit/`, `manifest.json`
|
| 20 |
+
|
| 21 |
+
### Estrutura de pastas do app
|
| 22 |
+
```text
|
| 23 |
+
birdnet-validator-hf-app/
|
| 24 |
+
app.py
|
| 25 |
+
requirements.txt
|
| 26 |
+
README.md
|
| 27 |
+
src/
|
| 28 |
+
domain/
|
| 29 |
+
services/
|
| 30 |
+
repositories/
|
| 31 |
+
auth/
|
| 32 |
+
ui/
|
| 33 |
+
cache/
|
| 34 |
+
telemetry/
|
| 35 |
+
cli/
|
| 36 |
+
hf_dataset_cli.py
|
| 37 |
+
tests/
|
| 38 |
+
unit/
|
| 39 |
+
integration/
|
| 40 |
+
docs/
|
| 41 |
+
architecture.md
|
| 42 |
+
operations.md
|
| 43 |
+
```
|
| 44 |
+
|
| 45 |
+
## 3) Definicoes tecnicas fechadas
|
| 46 |
+
- UI: Gradio no Hugging Face Space
|
| 47 |
+
- Armazenamento principal: Hugging Face Datasets
|
| 48 |
+
- Granularidade: 1 dataset por projeto
|
| 49 |
+
- Ingestao: CLI separada com `huggingface_hub`
|
| 50 |
+
- Identidade de deteccao: `detection_key` estavel e imutavel
|
| 51 |
+
- Leitura de audio: sob demanda por `audio_id`
|
| 52 |
+
- Cache local: efemero (RAM + /tmp), com limite por tamanho e TTL
|
| 53 |
+
- Pos-validacao: limpar buffer em memoria e arquivo temporario local
|
| 54 |
+
- Nunca deletar audio original do dataset remoto durante validacao
|
| 55 |
+
|
| 56 |
+
## 4) Definicao de pronto (DoD)
|
| 57 |
+
Uma tarefa so e considerada pronta quando:
|
| 58 |
+
1. Codigo implementado com testes minimos
|
| 59 |
+
2. Logs de erro e sucesso adicionados
|
| 60 |
+
3. Documentacao curta atualizada
|
| 61 |
+
4. Validada em ambiente local
|
| 62 |
+
5. Sem regressao em fluxo principal
|
| 63 |
+
|
| 64 |
+
## 5) Epics e backlog por prioridade
|
| 65 |
+
|
| 66 |
+
## Epic A - Bootstrap do novo app e arquitetura base (P0)
|
| 67 |
+
### A1. Criar novo repositorio do app
|
| 68 |
+
- Descricao: inicializar `birdnet-validator-hf-app` com estrutura base
|
| 69 |
+
- Entregavel: repo criado + branch strategy + CI minima
|
| 70 |
+
- Criterio de aceite: app sobe local com tela inicial vazia
|
| 71 |
+
|
| 72 |
+
### A2. Definir modelos de dominio
|
| 73 |
+
- Descricao: `Project`, `Detection`, `Validation`, `User`, `Role`, `IndexManifest`
|
| 74 |
+
- Entregavel: dataclasses/pydantic + validacoes de schema
|
| 75 |
+
- Criterio de aceite: validacao de payload passa em testes unitarios
|
| 76 |
+
|
| 77 |
+
### A3. Definir contratos de repositorio
|
| 78 |
+
- Descricao: interfaces para ProjectRepo, DetectionRepo, ValidationRepo, AuthRepo
|
| 79 |
+
- Entregavel: interfaces + implementacao fake para teste
|
| 80 |
+
- Criterio de aceite: casos basicos executam sem dependencia externa
|
| 81 |
+
|
| 82 |
+
## Epic B - CLI de ingestao para Hugging Face (P0)
|
| 83 |
+
### B1. Comando create-project
|
| 84 |
+
- Descricao: criar estrutura do dataset remoto por projeto
|
| 85 |
+
- Entregavel: comando `create-project`
|
| 86 |
+
- Criterio de aceite: estrutura minima criada no repo dataset
|
| 87 |
+
|
| 88 |
+
### B2. Comando sync-audio em lotes
|
| 89 |
+
- Descricao: upload de audios em batch com retry e resume idempotente
|
| 90 |
+
- Entregavel: comando `sync-audio --resume`
|
| 91 |
+
- Criterio de aceite: interrupcao de rede nao duplica arquivos
|
| 92 |
+
|
| 93 |
+
### B3. Comando build-index
|
| 94 |
+
- Descricao: gerar `manifest.json` + shards de deteccoes
|
| 95 |
+
- Entregavel: pasta `index/` com particoes e checksums
|
| 96 |
+
- Criterio de aceite: manifesto referencia somente arquivos existentes
|
| 97 |
+
|
| 98 |
+
### B4. Comando verify-project
|
| 99 |
+
- Descricao: checar consistencia audio x index x deteccoes
|
| 100 |
+
- Entregavel: relatorio de saude do projeto
|
| 101 |
+
- Criterio de aceite: retorna codigo de erro quando houver inconsistencias
|
| 102 |
+
|
| 103 |
+
## Epic C - Leitura paginada e audio sob demanda (P0)
|
| 104 |
+
### C1. Detection queue paginada
|
| 105 |
+
- Descricao: listar deteccoes por pagina + filtros
|
| 106 |
+
- Entregavel: API interna de pagina com cursor/offset
|
| 107 |
+
- Criterio de aceite: navegar 50k deteccoes sem travar UI
|
| 108 |
+
|
| 109 |
+
### C2. Download individual de audio
|
| 110 |
+
- Descricao: baixar so o audio da deteccao ativa
|
| 111 |
+
- Entregavel: `AudioFetchService.fetch(audio_id)`
|
| 112 |
+
- Criterio de aceite: sem pre-download global de dataset
|
| 113 |
+
|
| 114 |
+
### C3. Cache efemero com limpeza
|
| 115 |
+
- Descricao: LRU/TTL em RAM e /tmp
|
| 116 |
+
- Entregavel: `CacheManager` com `cleanup_after_validation()`
|
| 117 |
+
- Criterio de aceite: arquivo temporario removido apos salvar validacao
|
| 118 |
+
|
| 119 |
+
### C4. Prefetch curto
|
| 120 |
+
- Descricao: prefetch dos proximos N audios
|
| 121 |
+
- Entregavel: worker simples de prefetch
|
| 122 |
+
- Criterio de aceite: melhora p95 de carregamento sem extrapolar limite de cache
|
| 123 |
+
|
| 124 |
+
## Epic D - Persistencia de validacoes no HF Dataset (P0)
|
| 125 |
+
### D1. Modelo append-only de eventos
|
| 126 |
+
- Descricao: salvar validacoes em log de eventos por projeto
|
| 127 |
+
- Entregavel: `validations/events-YYYYMMDD.parquet` (ou csv shard)
|
| 128 |
+
- Criterio de aceite: toda alteracao gera evento auditavel
|
| 129 |
+
|
| 130 |
+
### D2. Snapshot consolidado
|
| 131 |
+
- Descricao: materializar estado atual por `detection_key`
|
| 132 |
+
- Entregavel: `validations/current.parquet`
|
| 133 |
+
- Criterio de aceite: lookup por detection_key em tempo baixo
|
| 134 |
+
|
| 135 |
+
### D3. Controle de concorrencia
|
| 136 |
+
- Descricao: controle otimista por revisao/etag
|
| 137 |
+
- Entregavel: rejeicao de escrita concorrente conflitante + merge rule
|
| 138 |
+
- Criterio de aceite: dois validadores simultaneos nao perdem dados silenciosamente
|
| 139 |
+
|
| 140 |
+
## Epic E - Auth, papeis e isolamento por projeto (P0)
|
| 141 |
+
### E1. Login e sessao
|
| 142 |
+
- Descricao: autenticar usuarios e carregar perfil/papeis
|
| 143 |
+
- Entregavel: AuthService + sessao segura
|
| 144 |
+
- Criterio de aceite: usuario sem permissao nao entra em projeto nao autorizado
|
| 145 |
+
|
| 146 |
+
### E2. ACL por projeto
|
| 147 |
+
- Descricao: vincular usuario a um ou mais projetos
|
| 148 |
+
- Entregavel: autorizacao por projeto em todas rotas de dados
|
| 149 |
+
- Criterio de aceite: consultas sempre filtradas por projeto autorizado
|
| 150 |
+
|
| 151 |
+
### E3. Painel admin
|
| 152 |
+
- Descricao: criar/arquivar projeto, atribuir usuarios, ver progresso
|
| 153 |
+
- Entregavel: UI admin funcional
|
| 154 |
+
- Criterio de aceite: alteracoes refletidas imediatamente nas sessoes novas
|
| 155 |
+
|
| 156 |
+
## Epic F - UX de validacao e produtividade (P1)
|
| 157 |
+
### F1. Fluxo rapido de validacao
|
| 158 |
+
- Descricao: botoes de acao + avancar automaticamente
|
| 159 |
+
- Entregavel: fluxo Positivo/Negativo/Indeterminado/Pular
|
| 160 |
+
- Criterio de aceite: 1 clique para validar e ir para proximo
|
| 161 |
+
|
| 162 |
+
### F2. Filtros completos
|
| 163 |
+
- Descricao: especie, confianca, status, localidade, data
|
| 164 |
+
- Entregavel: filtros combinaveis
|
| 165 |
+
- Criterio de aceite: filtro composto retorna lista correta
|
| 166 |
+
|
| 167 |
+
### F3. Recuperacao de sessao
|
| 168 |
+
- Descricao: restaurar ultimo item e filtros
|
| 169 |
+
- Entregavel: SessionState persistido por usuario/projeto
|
| 170 |
+
- Criterio de aceite: recarregar pagina nao perde contexto principal
|
| 171 |
+
|
| 172 |
+
## Epic G - Observabilidade, qualidade e operacao (P1)
|
| 173 |
+
### G1. Logs estruturados
|
| 174 |
+
- Descricao: correlacao por usuario/projeto/request
|
| 175 |
+
- Entregavel: logger padrao JSON
|
| 176 |
+
- Criterio de aceite: erro rastreavel de ponta a ponta
|
| 177 |
+
|
| 178 |
+
### G2. Metricas de performance
|
| 179 |
+
- Descricao: p50/p95 fetch audio, taxa erro, throughput validacoes
|
| 180 |
+
- Entregavel: painel simples em admin
|
| 181 |
+
- Criterio de aceite: metrica atualiza em tempo quase real
|
| 182 |
+
|
| 183 |
+
### G3. Testes e hardening
|
| 184 |
+
- Descricao: unit + integracao + testes de carga basica
|
| 185 |
+
- Entregavel: suite minima automatizada
|
| 186 |
+
- Criterio de aceite: pipeline CI verde em PR
|
| 187 |
+
|
| 188 |
+
## 6) Roadmap por sprint (2 semanas cada)
|
| 189 |
+
|
| 190 |
+
## Sprint 0 - Preparacao
|
| 191 |
+
- A1, A2, A3
|
| 192 |
+
- Saida: arquitetura base pronta + app inicia local
|
| 193 |
+
|
| 194 |
+
## Sprint 1 - Ingestao e indice
|
| 195 |
+
- B1, B2, B3, B4
|
| 196 |
+
- Saida: projeto pode ser publicado em dataset com indice valido
|
| 197 |
+
|
| 198 |
+
## Sprint 2 - Core de leitura e cache
|
| 199 |
+
- C1, C2, C3
|
| 200 |
+
- Saida: app navega deteccoes e toca audio sob demanda com limpeza local
|
| 201 |
+
|
| 202 |
+
## Sprint 3 - Persistencia colaborativa
|
| 203 |
+
- D1, D2, D3
|
| 204 |
+
- Saida: validacoes salvas com auditoria e sem perda por concorrencia
|
| 205 |
+
|
| 206 |
+
## Sprint 4 - Seguranca e multi-projeto
|
| 207 |
+
- E1, E2, E3
|
| 208 |
+
- Saida: login + ACL por projeto + admin operacional
|
| 209 |
+
|
| 210 |
+
## Sprint 5 - UX e performance
|
| 211 |
+
- F1, F2, F3, C4
|
| 212 |
+
- Saida: fluxo de validacao rapido e estavel para volume alto
|
| 213 |
+
|
| 214 |
+
## Sprint 6 - Operacao e qualidade
|
| 215 |
+
- G1, G2, G3
|
| 216 |
+
- Saida: observabilidade, testes e readiness de producao
|
| 217 |
+
|
| 218 |
+
## 7) Criticos de arquitetura (nao negociaveis)
|
| 219 |
+
1. Nao carregar dataset inteiro em memoria
|
| 220 |
+
2. Audio sempre sob demanda por item
|
| 221 |
+
3. Cleanup local obrigatorio apos validacao
|
| 222 |
+
4. detection_key imutavel
|
| 223 |
+
5. Isolamento forte por projeto e por usuario
|
| 224 |
+
|
| 225 |
+
## 8) Riscos e mitigacoes
|
| 226 |
+
- Risco: contenção ao gravar validacoes no mesmo dataset
|
| 227 |
+
- Mitigacao: append-only + snapshots + micro-batches
|
| 228 |
+
- Risco: latencia de rede no fetch de audio
|
| 229 |
+
- Mitigacao: cache efemero + prefetch curto + retries
|
| 230 |
+
- Risco: crescimento de custo por requests
|
| 231 |
+
- Mitigacao: politicas de cache e compressao de artefatos de indice
|
| 232 |
+
- Risco: conflito entre validadores
|
| 233 |
+
- Mitigacao: versao otimista + log de conflitos + merge deterministico
|
| 234 |
+
|
| 235 |
+
## 9) Entregaveis finais da v1
|
| 236 |
+
1. Repositorio do app no ar em HF Space
|
| 237 |
+
2. CLI funcional para publicar projetos no HF Dataset
|
| 238 |
+
3. Validacao multi-projeto com usuarios/papeis
|
| 239 |
+
4. Download individual de audio com limpeza local
|
| 240 |
+
5. Persistencia de validacoes com auditoria
|
| 241 |
+
6. Guia de operacao para onboarding de novos projetos
|
| 242 |
+
|
| 243 |
+
## 10) Proxima acao recomendada imediata
|
| 244 |
+
Executar Sprint 0 e Sprint 1 antes de qualquer migracao de dados historicos.
|