Skip to content

Repertórios — Decisões de Design

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

DEC-01: Ordem dos itens armazenada como JSON array no cabeçalho do repertório

Contexto: A ordem de exibição dos itens de um repertório precisa ser controlada pelo usuário, independente da ordem de inserção na tabela item_repertorio.

Decisão: O campo ordem_musicas TEXT DEFAULT '[]' no registro do repertório armazena um array JSON de id_item_repertorio na ordem desejada. Toda operação de adicionar, remover ou reordenar itens atualiza este campo atomicamente.

Alternativas descartadas:

  • Coluna posicao INTEGER em item_repertorio — exigiria UPDATE em N linhas a cada reordenação; sujeito a inconsistências.
  • Ordenação por data_criacao — não reflete intenção do usuário.

Consequências:

  • ✅ Reordenação em uma única operação de UPDATE no cabeçalho 🟢
  • ✅ Consulta de itens em ordem correta requer deserialização do JSON no cliente 🟢
  • ⚠️ Se o array ficar dessincronizado com os itens reais, a ordem pode conter IDs obsoletos 🟡

Confiança: 🟢 — confirmado em Repertorio.ts + migration v8.

DEC-02: Soft-delete em vez de exclusão física

Contexto: Repertórios excluídos pelo usuário precisam sumir da interface, mas a equipe considerou a possibilidade de sincronização futura com a API.

Decisão: Ao excluir um repertório, o campo data_exclusao é preenchido com o timestamp atual. Consultas de listagem filtram com WHERE data_exclusao IS NULL.

Alternativas descartadas:

  • DELETE físico — irreversível; impede rastreamento de exclusões para sincronização futura.

Consequências:

  • ✅ Repertórios excluídos permanecem no banco para auditoria ou recuperação futura 🟡
  • ⚠️ Sem purga periódica, o banco pode acumular registros inativos ao longo do tempo 🟡

Confiança: 🟢 — confirmado em deactivateRepertorio + migration v8.

DEC-03: Dual slug (referencia + corrente) para rastreamento de origem

Contexto: Um usuário pode importar um repertório de outra conta e depois re-compartilhá-lo. O slug do compartilhamento original deve ser preservado para rastreamento de proveniência.

Decisão: O repertório tem dois campos de slug:

  • slug_referencia: slug original de quem criou o repertório (nunca muda após importação)
  • slug_corrente: slug do último compartilhamento pelo dono atual

Alternativas descartadas:

  • Um único campo slug — perderia a informação de origem ao re-compartilhar.

Consequências:

  • ✅ Proveniência rastreável; importações futuras do mesmo slug são deduplicadas 🟢
  • ⚠️ Lógica de comparação de slugs precisa considerar ambos os campos 🟢

Confiança: 🟢 — confirmado em RepertorioSlug + CompartilharService.

DEC-04: Múltiplas estratégias para geração de folheto (Strategy Pattern)

Contexto: Gerar um folheto PDF requer enviar o repertório para a API, o que depende de autenticação. O sistema precisa degradar graciosamente quando o usuário não está logado ou quando a API está indisponível.

Decisão: FolhetoService usa o padrão Strategy com três implementações:

  1. GerarFolhetoComSlugStrategy — autentica + POST à API + abre link com slug
  2. GerarFolhetoBase64Strategy — serializa para Base64 + abre link sem autenticação
  3. GerarFolhetoNoopStrategy — sem ação (fallback seguro)

Consequências:

  • ✅ Degradação graciosa: Base64 funciona mesmo sem conta 🟢
  • ✅ Estratégia selecionável em runtime conforme contexto 🟢
  • ⚠️ URLs com Base64 podem ser longas demais para alguns clientes HTTP 🟡

Confiança: 🟢 — confirmado em FolhetoService.ts.

DEC-05: Reordenação de itens temporariamente desabilitada (DT-08)

Contexto: A UI de reordenação de itens foi implementada, mas a biblioteca de reordenação (react-native-reorderable-list) apresentou instabilidades após upgrades do React Native.

Decisão: O botão de reordenação foi desabilitado na UI com o commit fix(repertorio): desabilitado reordenação por enquanto. A lógica de ordem_musicas permanece íntegra no backend.

Status: Dívida técnica ativa (DT-08). A reabilitação depende de uma versão estável da biblioteca de reordenação compatível com React Native 0.84+.

Confiança: 🟢 — confirmado via commit mensagem.

DEC-06: Mensagem de compartilhamento em Markdown compatível com WhatsApp

Contexto: O principal canal de compartilhamento de repertórios é o WhatsApp, que suporta um subconjunto limitado de Markdown (negrito, itálico, código inline).

Decisão: gerarMensagemCompartilhamento formata a mensagem usando apenas os marcadores suportados pelo WhatsApp: *texto* (negrito), _texto_ (itálico), `código` (monoespacado). Markdown de tabelas e títulos são evitados.

Confiança: 🟢 — confirmado em RepertorioService.ts + commit feat(share music): improve whastsapp markdown support.