Skip to content

Sugestão de Repertório — Design Técnico

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

Interface

Redux / Thunks (SugestoesRepertorioAction)

Símbolo Assinatura Observação
baixar () Download do banco remoto + importarSugestoes
buscar (window, parametros) Pesquisa com window (lista/prévia) e parâmetros
carregarPrevia () _pesquisar com limite = 4, window = prévia
carregarLista (parametros?) _pesquisar sem limite, window = lista
limpar (window) Action síncrona que limpa slice do window informado

Repository (BibliotecaSugestoesRepertorioRepository)

Símbolo Assinatura Observação
popularSugestoesIniciais () Popula a partir de asset se COUNT(*) = 0
sumCrc32 () Soma de CRC32 para detecção de atualização
importarSugestoes () ATTACH cache + DELETE total + INSERT
findBy (params, limite?) Filtro em memória com fusearch + data futura
findByDiaLiturgico (idRomcal, ano?) Filtra por chave_ciclo_liturgico exata
findAll () (private) SQL com json_group_array para montar itens[]

Modelo de Dados

interface SugestaoRepertorio {
  id_sugestao_repertorio: number;
  chave_ciclo_liturgico?: ChaveCicloLiturgico; // "A:celebracao_id" | "celebracao_id"
  ano_liturgico?: string;
  id_romcal?: string;
  titulo: string;
  resumo: string;
  itens: ItemSugestaoRepertorio[];
  metadata: { referencias: string[] };
  cor: CorLiturgica; // enriquecido do calendário romcal
  data: DateString; // enriquecido do calendário romcal
  tempoLiturgico?: TempoLiturgico; // enriquecido
  crc32: number;
}

interface ItemSugestaoRepertorio {
  id_musica: number;
  momento?: string;
  titulo_musica: string;
  trecho_letra: string;
  metadata: { referencia?: string; indice?: string; ignorar?: boolean };
}

Fluxo Principal — Listar e Filtrar

  1. SugestoesRepertorioListaScreen monta → dispatch(SugestoesRepertorioAction.carregarLista())
  2. _pesquisar chama BibliotecaSugestoesRepertorioRepository.findBy(params)
  3. findAll() executa SQL com json_group_array + JOIN músicas; exclui itens ignorar = true
  4. findBy enriquece com calendário romcal (data, cor, tempoLiturgico)
  5. Filtra por data >= hoje; ordena ASC; aplica fuseSearch se termoBusca; aplica tempoLiturgico
  6. Store atualiza window lista → FlatList renderiza

Fluxo: Converter em Repertório

  1. Usuário em SugestaoRepertorioDetalhesScreen seleciona itens (modo seleção)
  2. "Criar repertório" → sugestao.itens.filter(selecionados) → verifica mínimo 1 item
  3. dispatch(RepertoriosAction.criarPorSugestao(sugestaoAcatada)).unwrap()
  4. Toast de sucesso; navega para o repertório criado

Fluxo: Sincronização Remota

  1. SugestoesRepertorioAction.baixar chama new SugestoesRepertorioService().baixarSugestoes()
  2. Guard: downloadEmAndamento estático (igual a ObraService)
  3. Download de Api.APP_BIBLIOTECA_SUGESTOES_REPERTORIO_SQLITE() para cachePath('sugestoes_repertorio.db')
  4. BibliotecaSugestoesRepertorioRepository.importarSugestoes():
  5. ATTACH cache como sugestoesImport
  6. DELETE total de sugestao_repertorio
  7. INSERT de todos os registros do alias
  8. DETACH em finally

Dependências

  • CalendarioLiturgicoService — enriquecimento de data/cor/tempoLiturgico
  • TextUtil.fuseSearch — busca fuzzy em memória
  • RepertoriosAction.criarPorSugestao — criação do repertório a partir da sugestão
  • AssetDatabasePreparator + AssetBanco.REPERTORIOS — seeds iniciais

Decisões de Design Identificadas

Decisão Evidência no código Confiança
Sugestões não têm data própria — derivada do calendário romcal findBy → calendarios.get(chave) 🟢
Substituição total (DELETE + INSERT) ao importar upsertSugestoes — DELETE WHERE 1=1 🟢
Busca fuzzy em JS (não FTS5) com fuse.js TextUtil.fuseSearch 🟡
Dois SugestoesRepertorioWindow (lista e prévia) no store SugestoesRepertorio.types.ts 🟢

Estado Interno

// SugestoesRepertorioWindow
enum SugestoesRepertorioWindow {
  previa,
  lista,
}

// Slice: dois slices independentes (lista e prévia)
// cada um com: ids[], entities{}, estado: EstadoRequisicao

Riscos e Lacunas

  • 🟡 Busca fuzzy em memória pode ser lenta com catálogo grande — sem paginação no filtro JS
  • 🟡 findAll exclui itens ignorar = true no SQL — itens ignorados não existem na memória para rastrear
  • 🔴 baixarSugestoes mutex estático: comportamento após reinício do app não determinístico
  • 🟡 Sugestões sem chave_ciclo_liturgico são silenciosamente omitidas — sem indicativo ao usuário