Skip to content

Biblioteca

Gerado pelo Writer (Reversa) em 2026-05-11 doc_level: detalhado | Granularidade: híbrida (módulo + casos de uso)

Visão Geral

Módulo responsável por gerenciar o catálogo de obras musicais disponíveis para download, controlar a instalação de músicas no banco de dados local via arquivos SQLite externos (ATTACH/DETACH), e expor links externos de recursos da CNBB (Liturgia Diária, Sugestões de Repertório).

Responsabilidades

  • Listar o catálogo de obras disponíveis via API remota
  • Comparar CRC32 entre obra remota e exemplar local para detectar atualizações
  • Baixar arquivos .db de obras para o cache do dispositivo
  • Importar músicas, livros e índices do banco temporário para o banco principal via ATTACH
  • Registrar o exemplar instalado em exemplar_biblioteca
  • Expor links externos para recursos da CNBB

Regras de Negócio

  • Uma obra só pode ser baixada se não houver outro download em andamento (downloadEmAndamento) 🟢
  • A detecção de obras desatualizadas usa comparação de crc32 entre o catálogo remoto e exemplar_biblioteca.crc32 🟢
  • Obras com disponivel = false são filtradas da listagem antes de exibição ao usuário 🟢
  • A importação usa ATTACH DATABASE para operações atômicas — o DETACH ocorre em bloco finally garantindo limpeza 🟢
  • Músicas são sincronizadas via INSERT ON CONFLICT DO UPDATE baseando-se em crc32 diferente 🟢
  • Ao registrar um exemplar, o exemplar anterior da mesma obra é desativado (ativo = false) antes de criar o novo 🟢
  • Obras desatualizadas (SituacaoItemObra.NAO_ATUALIZADA) são baixadas automaticamente ao fechar o modal 🟢
  • O módulo também importa sugestões de repertório via API separada (/repertorios) 🟢

Requisitos Funcionais

ID Requisito Prioridade Critério de Aceite
RF-01 Listar catálogo de obras com situação de instalação Must Lista exibe obras com status: ATUALIZADA / NAO_BAIXADA / NAO_ATUALIZADA
RF-02 Baixar e importar obra selecionada para o banco local Must Músicas, livros e índices da obra aparecem na busca após importação
RF-03 Bloquear download simultâneo de obras Must Segunda tentativa de download enquanto há download em andamento lança erro
RF-04 Baixar automaticamente obras desatualizadas ao confirmar modal Should Obras com crc32 diferente do remoto são baixadas sem seleção manual
RF-05 Exibir links externos para Liturgia Diária e Sugestões de Repertório Could Cards abrem URLs corretas no browser externo

Requisitos Não Funcionais

Tipo Requisito inferido Evidência no código Confiança
Disponibilidade ATTACH/DETACH em bloco try/finally evita banco corrompido BibliotecaRepository.ts — importarObra 🟢
Segurança CRC32 valida integridade da obra baixada BibliotecaApi.ts — comparação crc32 🟢
Performance Download sequencial com espera de 2s entre obras no batch BibliotecaAction.ts — baixarObras + wait(2000) 🟢

Critérios de Aceitação

Dado que o usuário abre o modal de obras
Quando o catálogo remoto é carregado
Então a lista exibe obras ATUALIZADA, NAO_BAIXADA e NAO_ATUALIZADA com labels corretos

Dado que o usuário seleciona uma obra não baixada e confirma
Quando o download é disparado
Então as músicas da obra aparecem na busca após importação concluída

Dado que já existe um download em andamento
Quando o usuário tenta baixar outra obra simultaneamente
Então um erro é lançado com mensagem "Já existe uma obra sendo baixada no momento"

Dado que uma obra tem crc32 diferente do exemplar local
Quando o usuário fecha o modal de obras
Então a obra desatualizada é baixada automaticamente sem seleção explícita

Prioridade (MoSCoW)

Requisito MoSCoW Justificativa
Listar e baixar obras Must Caminho crítico — sem obras o app não tem músicas
Bloqueio de download simultâneo Must Proteção de integridade do banco local
Download automático de obras desatualizadas Should Mantém catálogo atualizado sem fricção
Links externos CNBB Could Recurso complementar, não bloqueia fluxo principal

Rastreabilidade de Código

Arquivo Função / Classe Cobertura
src/store/Biblioteca/Biblioteca.api.ts BibliotecaApi (RTK Query) 🟢
src/store/Biblioteca/Biblioteca.action.ts BibliotecaAction 🟢
src/service/ObraService.ts ObraService.baixarObra 🟢
src/repository/BibliotecaRepository.ts BibliotecaRepository.importarObra 🟢
src/view/screen/biblioteca/BibliotecaScreen.tsx BibliotecaScreen 🟢
src/view/screen/biblioteca/fragment/SelecaoObrasBibliotecaModal.tsx SelecaoObrasBibliotecaModal 🟢
src/service/BibliotecaService.ts BibliotecaService.abrirLink 🟢