Skip to content

Biblioteca — Design Técnico

Gerado pelo Writer (Reversa) em 2026-05-11 doc_level: detalhado

Interface

API Remota (RTK Query — BibliotecaApi)

Endpoint Método URL Retorno Observação
getObras GET /obras Obra[] Catálogo completo de obras disponíveis
getRepertorios GET /repertorios RepertorioDisponivel[] Lista de sugestões de repertório remotas
getItensObras — /obras + findExemplaresAtivos ObraItemListData[] queryFn customizada: combina API + banco local; filtra disponivel = false

Thunks (BibliotecaAction)

Símbolo Assinatura Observação
baixarObras (obras: Obra[]) Batch com progress notification; 2s delay entre obras; para se obras.length === 0
baixarObra (obra: Obra) Chama ObraService.baixarObra → BibliotecaRepository.importarObra
abrirLink (link: BibliotecaLink) Abre URL externa via BibliotecaService.abrirLink
carregar () Carrega findExemplaresAtivos — legado; substituído pelo getItensObras
atualizar () 🟡 Não lido completamente — verificar comportamento completo

Service (ObraService)

Símbolo Assinatura Observação
baixarObra (obra: Obra) Guard: downloadEmAndamento static; baixa para cachePath(id_obra.db); lança erro se já há download em curso

Repository (BibliotecaRepository)

Símbolo Assinatura Observação
findExemplaresAtivos () SELECT de exemplar_biblioteca WHERE ativo; retorna mapa {id_obra: ExemplarBiblioteca}
importarObra (obra, path) ATTACH cache → upsertMusicas → upsertLivros → registrarObra → DETACH

Fluxo Principal — Download e Importação de Obra

  1. Usuário abre modal → BibliotecaApi.getItensObras carrega catálogo + exemplares ativos
  2. Para cada obra: crc32 remoto vs exemplar_biblioteca.crc32 → SituacaoItemObra (ATUALIZADA / NAO_BAIXADA / NAO_ATUALIZADA)
  3. Obras com disponivel = false são filtradas antes da exibição
  4. Usuário seleciona obras não baixadas; ao confirmar, obras desatualizadas são adicionadas automaticamente
  5. BibliotecaAction.baixarObras([selecionadas, ...desatualizadas]) dispara o batch
  6. Para cada obra: ObraService.baixarObra → download do .db para cache/{id_obra}.db
  7. BibliotecaRepository.importarObra:
  8. Banco.attachFromCache('{id_obra}.db', 'toImport')
  9. upsertMusicas: INSERT ON CONFLICT DO UPDATE (apenas crc32 diferentes)
  10. upsertLivroEditoraEdicaoLivro + upsertCanticoLivro + deleteCreateSecaoLivroCanticoSecao (em paralelo)
  11. disableExemplarObra (desativa exemplar anterior) → createExemplarObra
  12. Banco.detach('toImport') em bloco finally
  13. Notification de progresso atualizada entre obras; toast de sucesso ou erro ao final

Fluxos Alternativos

  • Download em andamento: ObraService.downloadEmAndamento = true → lança Error — baixarObra captura e chama rejectWithValue
  • Obra já atualizada (crc32 igual): situacao = ATUALIZADA → não aparece no batch automático, usuário pode baixar manualmente se quiser
  • Erro de rede no download: baixarArquivo rejeita → ObraService.downloadEmAndamento = false em finally → rejectWithValue('Falhou')

Dependências

  • Banco (src/arch/persistence/Banco) — ATTACH/DETACH e execução de queries
  • baixarArquivo (src/arch/util/fs) — download de arquivo para cache
  • cachePath (src/arch/util/fs) — resolve caminho de cache por plataforma
  • Notification (src/util/Notification) — notificação de progresso para downloads em batch
  • BibliotecaApi (RTK Query) — catálogo remoto de obras

Decisões de Design Identificadas

Decisão Evidência no código Confiança
Mutex de download via variável static em ObraService ObraService.ts — downloadEmAndamento 🟢
Detecção de atualização por CRC32 (ADR-009) BibliotecaApi.ts — comparação crc32 🟢
Uso de ATTACH DATABASE para importação atômica BibliotecaRepository.ts — importarObra 🟢
Delay de 2s entre downloads para evitar sobrecarga BibliotecaAction.ts — wait(2 * 1000) 🟢
Obras disponivel = false ocultas na UI (soft-delete remoto) BibliotecaApi.ts — .filter(it => it.obra.disponivel) 🟢

Estado Interno

  • ObraService.downloadEmAndamento: boolean — mutex estático; reset no finally do download
  • exemplar_biblioteca (SQLite) — registro persistente de obras instaladas com ativo flag
  • Store Redux/RTK Query: BibliotecaApi gerencia cache de getItensObras

Riscos e Lacunas

  • 🟡 ObraService.downloadEmAndamento é um mutex estático não persistente — reinício do app libera o lock mesmo que download tenha travado
  • 🟡 atualizar thunk não foi lido completamente — comportamento exato não confirmado
  • 🔴 Sem verificação de espaço em disco antes do download
  • 🟡 Erro de rede exibe genérico "Falhou" — sem diferenciação entre timeout, sem conexão, ou servidor indisponível