Modelo de Dados

As entidades persistidas em Room que sustentam a biblioteca, o leitor e as configurações. Para o mecanismo de migração e o arquivo de banco em si, ver Banco de Dados.

Entidades

Ver Fontes Remotas para o modelo completo de fontes remotas.

Identificadores

FolderEntity e FileEntity usam como chave primária uma string derivada do document ID do SAF (Base64 do ID do documento), não um inteiro sequencial — o identificador de um item na biblioteca é, na prática, uma codificação da sua própria localização no sistema de arquivos. A pasta raiz da árvore usa o literal "root" como parentId.

Entidades sem relação direta com um arquivo específico do SAF (ReadingHistoryEntity, ReadingSessionEntity, ChapterPaginationCacheEntity) usam Long autoincrementado, por não terem um identificador natural próprio. BookmarkEntity usa chave composta (fileId, pageIndex), já que a combinação das duas é naturalmente única — no máximo um marcador por página de um arquivo.

Arquivos/pastas que vêm de uma fonte remota continuam usando FileEntity/FolderEntity — não há entidade separada por provedor. O que muda são campos extras, todos null para um item local: remoteSourceId/remoteLibraryId (qual fonte/biblioteca é dona do item), komgaBookId (Komga) ou remoteItemId/remoteVolumeId/remoteSeriesId (Kavita — capítulo/volume/série, os IDs que a própria API de progresso do Kavita exige no corpo da requisição), e localProgressUpdatedAt (carimbo de última mudança local de progresso — usado pelo merge de sync pra decidir se uma proteção "progresso local nunca regride" ainda vale ou se o servidor já pode ser tratado como fonte da verdade). RemoteLibraryEntity usa chave composta (sourceId, remoteLibraryId).

Relações são lógicas, não impostas pelo schema

Não há @ForeignKey declarado em nenhuma entidade — FileEntity.folderId, FolderEntity.parentId, CoverEntity.fileId e os demais vínculos entre tabelas são mantidos por convenção de código, não garantidos pelo banco. Remover um FolderEntity sem também remover os FileEntity filhos, por exemplo, não é impedido pelo schema; é responsabilidade de quem escreve a operação (ver como o Scanner faz isso).

Isso não significa ausência de índices: as colunas mais consultadas (folderId+name, isFavorite, isRead+currentPage em files; parentId+name, isFavorite em folders; a combinação completa de chave em chapter_pagination_cache) têm @Index dedicado — só as chaves estrangeiras em si não são impostas.

Configurações como linhas, não colunas

Preferências do usuário não viram uma coluna nova a cada funcionalidade — são todas linhas de key/value na tabela settings. As chaves e os valores padrão de cada uma vivem como constantes no companion object do repositório central (ver 02 - Arquitetura Geral).

Credencial remota não é uma coluna de tabela

A credencial de uma fonte remota (senha, API key, Auth Key) não fica em remote_sources nem em nenhuma outra tabela do Room — fica cifrada (AES/GCM) num SharedPreferences separado, com a chave de criptografia por sourceId mantida no Android Keystore, nunca em texto plano e nunca exportável junto de um dump do banco.

Cache de paginação do EPUB é sensível ao viewport

Diferente das demais entidades de cache (que dependem só do arquivo), ChapterPaginationCacheEntity é indexada pela combinação de arquivo + capítulo + zoom de texto + largura + altura da tela. Isso reflete uma particularidade real do Leitor EPUB: quantas páginas um capítulo ocupa depende de como o texto foi paginado, e isso muda se o tamanho da fonte for alterado ou o aparelho girar de orientação — o mesmo capítulo pode ter contagens de página completamente diferentes em cada combinação.