Skip to content

Busca de Músicas

Gerado pelo Writer (Reversa) em 2026-05-11 Unit: musicas/busca-musicas

Visão Geral

Sub-caso de uso focado exclusivamente na experiência de busca: entrada do usuário, classificação do termo, execução da query SQLite/FTS5 e retorno de resultados paginados com snippet destacado.

Responsabilidades

  • Receber o termo digitado pelo usuário e classificá-lo (vazio / índice / texto)
  • Executar a estratégia de busca correta no SQLite
  • Retornar resultados paginados com hasNextPage
  • Exibir snippet do trecho encontrado com destaque do termo buscado
  • Aplicar filtros secundários (livro selecionado, rótulo)

Regras de Negócio

  • Normalização NFKD remove acentos antes do MATCH FTS5 🟢
  • Cada token recebe sufixo * para match por prefixo 🟢
  • Duplos ** são removidos após o join 🟢
  • A busca por índice só reconhece inteiros (parseInt válido) — alfanuméricos caem na busca textual 🟡
  • Título da música tem peso BM25 = 50; letra tem peso = 5 (título é mais relevante) 🟢
  • Snippet é limitado a TOTAL_TOKENS (12 phone / 24 tablet) 🟢

Requisitos Funcionais

| ID | Requisito | Prioridade | Critério de Aceite | | ----- | -------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------ | --- | ---------------------------------------- | | RF-01 | Classificar termo como índice, texto ou vazio | Must | "23" → índice; "ave" → texto; "" → vazio | | RF-02 | Normalizar termo: NFKD + remover não-alfanumérico + sufixo * | Must | "Avé María" → "ave* maria*" na query FTS5 | | RF-03 | Executar busca vazia com ORDER BY título | Must | Lista retorna todas as músicas ordenadas alfabeticamente | | RF-04 | Executar busca por índice com WHERE cantico_livro.indice = ? | Must | "23" com livro selecionado retorna música de índice 23 | | RF-05 | Executar busca FTS5 com ranking bm25(50,5) | Must | "maria" retorna músicas com "Maria" no título antes de músicas apenas na letra | | RF-06 | Paginar resultados com LIMIT n+1 e expor hasNextPage | Must | Última página retorna hasNextPage=false; páginas intermediárias true | | RF-07 | Filtrar resultados por livro selecionado | Should | Apenas músicas do livro ativo aparecem | | RF-08 | Filtrar resultados por rótulo litúrgico | Should | Apenas músicas com o rótulo selecionado aparecem | | RF-09 | Exibir snippet do trecho encontrado com marcadores de destaque | Should | Marcadores | | delimitam o termo na string de snippet |

Critérios de Aceitação

Dado que o campo de busca está vazio
Quando a lista é carregada
Então músicas são exibidas em ordem alfabética por título

Dado que o usuário digitou "23" com o livro "Canto Eucarístico 5a ed." selecionado
Quando a busca é executada
Então a música com índice 23 naquele livro é retornada

Dado que o usuário digitou "Avé María"
Quando a busca FTS5 é executada
Então a normalização produz "ave* maria*" e músicas com "Ave Maria" no título aparecem primeiro

Dado que há 51 músicas no resultado e o pageSize é 50
Quando a primeira página é carregada
Então hasNextPage é true e apenas 50 músicas são exibidas

Dado que o usuário selecionou o rótulo "Entrada"
Quando a busca é executada
Então apenas músicas marcadas com o rótulo "Entrada" são retornadas

Rastreabilidade de Código

Arquivo Função / Classe Cobertura
src/repository/musicas/MusicasRepository.ts findAllBy, getDetalhesTermoBusca, BuscaStrategies 🟢
src/repository/musicas/MusicaConfiguration.ts TOTAL_TOKENS, TOTAL_CARACTERES 🟢
src/store/Musicas/Musicas.action.ts buscarMusicas 🟢