Skip to content

Liturgia — Módulo

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

Visão Geral

Módulo responsável por exibir a liturgia do dia (leituras, celebrações, orações, antífonas) buscada da API DANCRF com cache SQLite de 24h de TTL, e pelo calendário litúrgico romano calculado offline via biblioteca romcal com cache em memória por ano civil.

Contexto

A liturgia é exibida na LiturgiaDoDiaScreen, acessível a partir de sugestões de repertório (que usam a data do calendário romcal) e como tela direta. O módulo é transversal: CalendarioLiturgicoService é consumido também pelo módulo de sugestão de repertório para enriquecimento de datas e cores litúrgicas.

Regras de Negócio

  • O calendário litúrgico é calculado offline pela biblioteca romcal — não depende de API 🟢
  • Cache do calendário romcal é em memória (por ano civil) — não persiste entre execuções do app 🟢
  • A liturgia diária (leituras, orações) vem da API DANCRF (/api/v3/) 🟢
  • Cache SQLite com TTL de 24h; dados com mais de 1 ano são purgados automaticamente 🟢
  • Status 404 da API é tratado como "sem liturgia para este dia", não como erro técnico 🟢
  • Fallback: se API falha mas há cache (mesmo expirado), usa o cache desatualizado 🟢

Requisitos Funcionais

ID Requisito Prioridade Critério de Aceite
RF-01 Exibir liturgia do dia (leituras, celebrações, orações) Must Dados da API exibidos na tela para a data passada via params
RF-02 Cache SQLite fresco por 24h Should Segunda consulta no mesmo dia usa cache sem chamar API
RF-03 Fallback para cache expirado em caso de erro de rede Should Dados exibidos mesmo offline, com indicação de desatualizado
RF-04 Calendário romcal offline para ano corrente e seguinte Must getCalendariosLiturgicos retorna Map sem chamada de rede
RF-05 Purgar cache de liturgia mais antigo que 1 ano Could pruneStale removendo entradas > 365 dias

Critérios de Aceitação

Dado que o usuário abre a tela de liturgia para uma data com dados na API
Quando a tela é renderizada
Então leituras, orações, antífonas e celebrações da data são exibidas

Dado que o usuário abre a mesma tela uma segunda vez no mesmo dia
Quando a tela renderiza
Então nenhuma chamada HTTP é feita (cache fresco)

Dado que a API retorna 404 para uma data
Quando a tela renderiza
Então a UI exibe mensagem "sem liturgia para este dia" sem erro técnico

Dado que a API está offline e há cache expirado disponível
Quando a tela renderiza
Então dados do cache expirado são exibidos como fallback

Rastreabilidade de Código

Arquivo Função / Classe Cobertura
src/service/CalendarioLiturgicoService.ts getCalendariosLiturgicos, getDiasLiturgicosPorData, getDiasLiturgicosPorMes 🟢
src/repository/LiturgiaCacheRepository.ts find, findFresh, save, pruneStale 🟢
src/store/Liturgia/Liturgia.api.ts LiturgiaApi, getLiturgiaPorData 🟢
src/model/liturgia/LiturgiaDia.ts DancrfMapper, LiturgiaDiaDancrf 🟢
src/view/screen/LiturgiaDoDiaScreen.tsx LiturgiaDoDiaScreen 🟢
src/arch/persistence/migration/v15_liturgia_cache.sql.ts migration 🟢

Dependências Externas

Dependência Uso Confiança
romcal + @romcal/calendar.brazil Calendário litúrgico offline 🟢
DANCRF API Parceiros.LITURGIA Liturgia diária (leituras, orações) 🟢
@reduxjs/toolkit/query (RTK Query) Fetch + caching endpoint 🟢
Banco (SQLite) Cache de liturgia diária 🟢