Skip to content

Sugestão de Repertório

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 sugestões de repertório litúrgico pré-definidas, associando cada sugestão a um dia do calendário litúrgico (via romcal), permitindo busca, filtragem por tempo litúrgico e conversão em repertório editável.

Responsabilidades

  • Manter banco local de sugestões de repertório (populado a partir de assets ou via download)
  • Associar sugestões ao calendário litúrgico (data, cor, tempo litúrgico)
  • Expor listagem com filtros de busca e tempo litúrgico
  • Exibir detalhes de cada sugestão com itens e músicas
  • Converter sugestão em repertório editável, respeitando itens marcados como ignorar

Regras de Negócio

  • Sugestões são populadas inicialmente a partir de arquivo asset se o banco local estiver vazio 🟢
  • Itens com metadata.ignorar = true são excluídos da query e não aparecem na listagem de itens 🟢
  • A data de cada sugestão é derivada do calendário romcal via chave_ciclo_liturgico, não armazenada diretamente 🟢
  • Sugestões sem correspondência no calendário romcal (calendarios.has() = false) são omitidas da listagem 🟢
  • A listagem exibe apenas sugestões com data ≥ hoje (futuras/presentes), ordenadas por data ASC 🟢
  • A busca textual usa TextUtil.fuseSearch nos campos titulo 🟢
  • Ao converter em repertório, itens com ignorar = true são filtrados; ao menos 1 item é obrigatório 🟢
  • Sugestões são substituídas totalmente no banco ao importar novo arquivo (DELETE + INSERT) 🟢

Requisitos Funcionais

ID Requisito Prioridade Critério de Aceite
RF-01 Listar sugestões de repertório futuras com data e cor litúrgica Must Lista exibe sugestões ordenadas por data, com cor e tempo litúrgico
RF-02 Filtrar sugestões por texto (fuzzy search no título) Should Busca retorna sugestões relevantes com debounce de 500ms
RF-03 Filtrar sugestões por tempo litúrgico Should Chip de filtro altera resultado da listagem
RF-04 Exibir detalhes da sugestão com itens e músicas Must Tela de detalhes exibe título, data litúrgica, cor e lista de itens
RF-05 Converter sugestão em repertório Must Repertório criado com itens selecionados; ao menos 1 item obrigatório
RF-06 Sincronizar sugestões via download do banco remoto Should Download substitui banco local totalmente; novas sugestões disponíveis

Requisitos Não Funcionais

Tipo Requisito inferido Evidência no código Confiança
Disponibilidade Seeds de assets garantem funcionamento offline inicial popularSugestoesIniciais — AssetBanco.REPERTORIOS 🟢
Performance Busca fuzzy em memória (sem FTS5) — pode degradar com volume grande TextUtil.fuseSearch em array JS 🟡
Performance Debounce de 500ms na busca textual SugestoesRepertorioListaScreen.tsx — debounce 500 🟢

Critérios de Aceitação

Dado que o banco de sugestões está vazio (primeira instalação)
Quando o app inicializa
Então as sugestões do arquivo asset são importadas automaticamente

Dado que o usuário filtra por texto "Natal"
Quando a busca é executada (após 500ms de debounce)
Então apenas sugestões com "Natal" no título aparecem

Dado que o usuário acessa detalhes de uma sugestão e seleciona alguns itens
Quando clica em "Criar repertório"
Então um repertório é criado apenas com os itens selecionados; ao menos 1 item é obrigatório

Dado que há sugestões com data passada
Quando a lista é carregada
Então sugestões com data < hoje não aparecem na listagem

Prioridade (MoSCoW)

Requisito MoSCoW Justificativa
Listar e visualizar sugestões Must Fluxo principal do módulo
Converter sugestão em repertório Must Objetivo de uso real do módulo
Busca e filtros Should Melhora descoberta; funciona sem
Sincronização remota Should Seeds garantem dados iniciais; atualização é opcional

Rastreabilidade de Código

Arquivo Função / Classe Cobertura
src/repository/BibliotecaSugestoesRepertorioRepository.ts BibliotecaSugestoesRepertorioRepository 🟢
src/service/SugestoesRepertorioService.ts SugestoesRepertorioService 🟢
src/store/SugestoesRepertorio/SugestoesRepertorio.action.ts SugestoesRepertorioAction 🟢
src/view/screen/sugestaoRepertorio/SugestoesRepertorioListaScreen.tsx SugestoesRepertorioListaScreen 🟢
src/view/screen/sugestaoRepertorio/SugestaoRepertorioDetalhesScreen.tsx SugestaoRepertorioDetalhesScreen 🟢
src/model/repertorio/SugestaoRepertorio.ts tipos SugestaoRepertorio, ItemSugestaoRepertorio 🟢