jrrribeiro commited on
Commit
8582d7f
·
1 Parent(s): 0bfe6f1

docs: add HF backlog and GitHub issues checklist

Browse files
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.