Guia de Administração

• Introdução
• O que é Hypatia?
• Como me registrar?
• Criação automática do Administrador
• Primeiro Acesso
• ⚠️ Importante
• Instalação
• Instalação Manual (modo local)
• Instalação Automática (Deploy com Nginx + Gunicorn)
• Requisitos do sistema
• Configuração
• Acessando o painel de configuração
• Configuração de E-mail (SMTP)
• 🔐 Segurança e boas práticas
• Testando o envio
• Gerenciando Usuários
• Acessando o painel de usuários
• Aprovação de novos registros
• Atribuindo papéis
• Editando e excluindo usuários
• 🔒 Segurança
• Gestão do Acervo
• Acessando o painel administrativo
• Adicionando novos livros
• Adicionando Livros Sem ISBN
• Como funciona a busca por ISBN
• Importar ISBNs em Lote
• Importando Catálogo por CSV
• Exportação de Catálogo e Relatórios
• Gerando relatórios em PDF
• 📌 Observações
• Gestão de Empréstimos
• Acessando o painel de empréstimos
• Solicitando e aprovando empréstimos
• Devolvendo obras
• Informações exibidas por empréstimo:
• 🔐 Controle de acesso
• 📌 Boas práticas

Introdução

O que é Hypatia?

 

Inspirado na tradição intelectual da figura histórica de Hipátia de Alexandria, o sistema busca unir a organização do conhecimento à praticidade digital, oferecendo uma interface moderna, responsiva e de fácil uso — acessível tanto para usuários casuais quanto para administradores de acervos mais complexos.

Como me registrar?

A primeira vez que o sistema Hypatia é executado em um novo ambiente, ele automaticamente cria uma conta administrativa padrão, garantindo que haja um usuário com acesso total ao painel de controle e às configurações internas da plataforma.

A senha padrão automática é:

login: admin
senha: admin123

🔒É imprescindível que essa senha seja alterada no primeiro login para não comprometer a segurança da sua instalação!

Esse processo faz parte da lógica de segurança do sistema, evitando que a plataforma fique sem um responsável técnico assim que for instalada.

Criação automática do Administrador

Ao rodar o sistema pela primeira vez, o Hypatia detecta a ausência de usuários no banco de dados e executa a seguinte ação:

• Cria um usuário com papel de administrador, com um endereço de e-mail e senha definidos previamente

• Esse usuário é armazenado no banco de dados com permissões administrativas completas.

Primeiro Acesso

Ao acessar a plataforma com esse usuário padrão, o sistema automaticamente detecta que a senha ainda é a original e solicita sua alteração imediata, como medida de segurança obrigatória.

Esse processo garante que o administrador troque a senha padrão por uma senha segura e pessoal antes de utilizar as funcionalidades críticas da plataforma.

⚠️ Importante

• O administrador inicial terá acesso a todos os módulos do sistema: gerenciamento de usuários, empréstimos, acervo, configurações e importações.

• Após a troca de senha, esse usuário permanecerá como o superusuário principal da instância.

• Recomenda-se não apagar essa conta, a menos que outra conta administrativa já tenha sido criada e esteja validada.

Instalação

Instalação Manual (modo local)

Este método é recomendado para testes, desenvolvimento ou uso em máquinas pessoais. O sistema é executado diretamente com o servidor de desenvolvimento do Flask.

1. Clonando o repositório

git clone git@github.com:LeoVichi/hypatia.git
cd hypatia

2. Criando um ambiente virtual Python

python3 -m venv venv
source venv/bin/activate        # No Windows: venv\Scripts\activate

3. Instalando as dependências

pip install -r requirements.txt

4. Executando a aplicação

python app.py

O sistema estará acessível via navegador em:

🌐 http://localhost:5000

Instalação Automática (Deploy com Nginx + Gunicorn)

Para ambientes de produção (como VPS Ubuntu), a instalação pode ser automatizada com o script setup_nginx.sh, que prepara o servidor com os serviços necessários.

1. Executar o script de configuração
   ./setup_nginx.sh

   Esse script configura automaticamente:

   • Um ambiente virtual isolado

   • Gunicorn como servidor WSGI

   • Um serviço systemd para manter o app ativo

   • Nginx como proxy reverso apontando para o Gunicorn

   • Permissões e pastas básicas do sistema

2. Reiniciar o serviço Nginx
   sudo systemctl restart nginx
   

Após a execução, a aplicação estará disponível no domínio configurado, geralmente em:

🌐 http://seu-servidor.com ou http://localhost (internamente)

Requisitos do sistema

• Python 3.8 ou superior

• Pip e venv instalados

• Git (para clonar o repositório)

• Servidor com suporte a systemd e Nginx (em caso de deploy)

• Porta 5000 (modo local) ou 80/443 (produção)

Configuração

Acessando o painel de configuração

• No menu superior, clique em Administração ▾

• Selecione a opção Configurações

• Você será direcionado à tela de Configurações do Sistema, onde poderá definir os parâmetros de envio de e-mail (SMTP)

Configuração de E-mail (SMTP)

• Servidor SMTP: o endereço do servidor de envio (ex: smtp.titan.email, smtp.gmail.com)

• Porta SMTP: geralmente 587 (TLS) ou 465 (SSL)

• Usar SSL: selecione Sim se o servidor usa SSL (porta 465)

• Usar TLS: selecione Sim se o servidor usa TLS (porta 587)

• Usuário SMTP: o endereço de e-mail usado como remetente

• Senha SMTP: a senha (ou senha de aplicativo) do e-mail

• Remetente Padrão: nome e e-mail exibido como origem das mensagens

Após preencher os campos, clique em Salvar Configurações.

🔐 Segurança e boas práticas

• A senha SMTP é armazenada de forma segura na base de dados e não é exibida depois de salva.

• É recomendável utilizar senhas de aplicativo (App Passwords) em serviços como Gmail ou Titan Mail.

• Apenas usuários com papel de admin têm acesso ao painel de configurações.

Testando o envio

Você pode testar a configuração de e-mail ao:

• Registrar uma nova conta (se o registro estiver ativado)

• Aprovar um novo usuário

• Ativar notificações administrativas

Em caso de erro no envio, verifique se a porta e o método de criptografia (SSL/TLS) estão corretamente configurados para o seu provedor.

Gerenciando Usuários

Acessando o painel de usuários

1. No menu superior, clique em Administração ▾

2. Selecione Gerenciar Usuários

Você será direcionado à lista completa de usuários cadastrados no sistema, com informações como:

• Nome

• E-mail

• Status de aprovação

• Papel (usuário ou administrador)

• Último acesso

Aprovação de novos registros

Se o sistema estiver com o registro automático ativado, novos usuários poderão se registrar diretamente na plataforma. Após o envio do formulário de cadastro e confirmação de e-mail (quando habilitada), o administrador deverá aprovar manualmente o acesso:

• Os usuários pendentes aparecerão destacados no painel.

• Basta clicar em “Aprovar” para liberar o acesso.

• Também é possível negar ou excluir cadastros indevidos.

Atribuindo papéis

Cada usuário possui um campo chamado “papel”, que define seu nível de acesso:

• usuario: acesso normal ao acervo, favoritos, referências, buscas e solicitações de empréstimo.

• admin: acesso total ao painel administrativo, incluindo gerenciamento de livros, empréstimos, configurações do sistema e usuários.

Para alterar o papel de um usuário, clique em “Editar”, selecione o novo papel e salve as alterações.

⚠️ Atenção: só conceda papel de administrador a usuários plenamente confiáveis.

Editando e excluindo usuários

Além de aprovar ou alterar o papel, o administrador pode:

• Atualizar dados de um usuário (nome, e-mail)

• Redefinir senhas manualmente

• Excluir permanentemente um usuário do sistema

Essas ações estão disponíveis na coluna Ações, ao lado de cada linha na tabela.

🔒 Segurança

• Apenas administradores têm acesso à gestão de usuários.

• A senha dos usuários é armazenada de forma criptografada e nunca é exibida.

• Toda atividade é registrada e vinculada ao ID do usuário correspondente.

Gestão do Acervo

Acessando o painel administrativo

1. No menu superior, clique em Administração ▾

2. Selecione a opção Administração de Catálogo

Você será direcionado ao painel completo de controle do acervo, onde poderá visualizar, editar e organizar todas as entradas registradas na base.

Adicionando novos livros

• No menu superior, clique em Administração ▾ → Adicionar Livros

• No campo ISBN, digite ou escaneie o código ISBN da obra

  💡 Dica: utilize um leitor de código de barras para capturar o ISBN impresso na quarta capa do livro.

• Clique no botão Pesquisar

• O sistema buscará automaticamente os dados do livro nas bases externas

• Verifique os campos preenchidos, edite se necessário, e clique em Salvar

Adicionando Livros Sem ISBN

1. No menu superior, clique em Administração ▾ → Adicionar Livros

2. Deixe o campo ISBN em branco

3. Marque a opção Este livro não possui ISBN

4. Preencha manualmente os campos obrigatórios, como Título, Autor e demais informações disponíveis

5. Clique em Salvar

   • 💡 Observação: Livros adicionados sem ISBN não poderão ser identificados em buscas automáticas externas, portanto, preencha o máximo de informações possível.

Seguem abaixo sugestões para preenchimento dos campos de forma a manter a uniformidade e o padrão do seu catálogo de acordo com as práticas usadas pelas melhores bibliotecas.

Título:

Preencha sempre com a primeira letra em maíuscula, evite usar maíusculas em substantivos simples e separe o subtítulo por dois pontos (:).
Ex.

A arte da eletrônica: circuitos eletrônicos e microeletrônica

Autor:

Opte por um padrão uniforme. Dois são mais comuns:

Sobrenome, Nome ou Nome Sobrenome

Ex.
Goethe, Johann Wolfgang von
ou
Johann Wolfgang von Goethe

Em caso de haver mais de um autor, separe-os por ponto e vírgula (;).

Ex.

Marx, Karl; Engels, Friedrich

Karl Marx; Friedrich Engels

Para Obras com editores, tradutores ou outras participações, é possível inserir a função entre parênteses.

Ex.

Homero; Manuel Odorico Mendes (Tradutor)

Para facilitar buscas, caso queira buscar por editoras, insira sempre o nome completo.

Ex.

 EdUFRJ - Editora da Universidade Federal do Rio de Janeiro

Ano:

Prefira sempre o ano em arábico com 4 dígitos. Informações como dias, meses ou estações do ano não costumam ser relevantes.

Ex.
2021

Gênero:

Esta categoria dependerá do que for mais conveniente para o acervo. Uma possibilidade é seguir o que está na Ficha Catalográfica da obra, ou então optar por algo que auxilie a segmentar de maneira eficiente o acervo. Se o acerto tiver variedade grande de obras dentro de um determinado assunto, pode ser preferível classificar de forma mais granular.

Ex.
Acervos com pouca variedade de obras sobre Tecnologia da Informação, pode classificar tudo dentro desse gênero, mas se a coleção requerer, pode ser segmentado por subgêneros como Programação, Engenharia de Redes, Segurança da Informação etc.

Idioma:

Aqui também tudo dependerá da preferência do gestor e pode ser registrado ou com o idioma por extenso,

ex.:

Português do Brasil, Italiano, Francês, etc., 

ou poderá ser empregado algum tipo de abreviação como

ex.:

PT-BR, IT, FR etc.

Como funciona a busca por ISBN

Ao informar um ISBN e acionar a busca, o sistema executa uma função que:

1. Limpa e normaliza o ISBN digitado, convertendo ISBN-10 em ISBN-13, se necessário.

2. Verifica se o livro já está cadastrado no banco de dados local para evitar duplicações.

3. Caso o livro seja novo, a função tenta buscar os metadados da obra em três fontes diferentes, nesta ordem:

1. Google Books

• Consulta a API pública do Google

• Retorna título, autores, editora e ano de publicação

2. CBL (Câmara Brasileira do Livro)

• Realiza scraping da busca oficial da CBL

• Garante cobertura de livros registrados no Brasil

3. Open Library

• Usa a API da OpenLibrary (Internet Archive)

• Complementa metadados quando não encontrados nas fontes anteriores

4. Se nenhuma das fontes retornar dados, o sistema informa que o livro não foi encontrado, e o administrador poderá preencher os campos manualmente.

5. Se os dados forem encontrados, o sistema pré-preenche automaticamente o formulário com:

   • Título

   • Autor(es)

   • Editora

   • Ano de publicação

   • ISBN padronizado

6. O administrador poderá revisar, editar ou complementar os dados antes de salvar.

Detalhes técnicos

• A busca usa uma função inteligente com tentativas e revezamento de user-agents, evitando bloqueios por IP.

• A ordem de consulta prioriza fontes com maior probabilidade de dados completos.

• Todas as chamadas são feitas com tratamento de exceções, retornos limpos e registros de log para depuração.

Importar ISBNs em Lote

A funcionalidade de importação em lote por ISBN permite ao administrador adicionar rapidamente várias obras ao catálogo apenas com base no número de ISBN. O sistema faz buscas automáticas em fontes como Google Books, OpenLibrary e CBL (Câmara Brasileira do Livro) para obter os dados bibliográficos de cada obra.

Como usar

1. Acesse o menu:
   Administração ▸ Administração de Catálogo

2. Na seção Importar Lista de ISBNs, clique em Selecionar Arquivo CSV.

3. Escolha um arquivo .csv contendo uma lista simples de ISBNs, com um ISBN por linha.
   Exemplo de conteúdo do arquivo:

9786551140006
9786556920580
9786556922546

Obs.Para evitar tempo limite de importação, recomendamos enviar arquivos com no máximo 10 ISBNs por vez. 

Importando Catálogo por CSV

Para facilitar a catalogação em massa de obras, o Hypatia permite que administradores importem livros diretamente a partir de arquivos no formato .csv. Essa funcionalidade é ideal para migrações de acervo, integração com outras plataformas ou digitalização de registros já existentes em planilhas.

O arquivo .csv deve conter uma linha de cabeçalho e, preferencialmente, seguir a seguinte estrutura:

titulo,autor,editora,ano,isbn

Cada linha representa uma obra. Exemplo:

Dom Casmurro,Machado de Assis,Nova Fronteira,1899,9788520920056
O Alienista,Machado de Assis,LPM,1882,9788525407071

Como importar livros

1. Acesse o menu Administração ▾ → Administração de Catálogo

2. Clique no botão Importar CSV

3. Selecione o arquivo .csv do seu computador

4. Clique em Importar

O sistema irá processar o arquivo linha por linha e registrar os livros válidos automaticamente.

O que o sistema faz automaticamente

• Remove duplicatas com base no ISBN

• Ignora linhas vazias ou malformadas

• Converte automaticamente tipos de dados (ano, título, etc.)

• Registra todos os livros com data de inclusão atual

Boas práticas

• Use UTF-8 como codificação do arquivo CSV para evitar erros com acentos

• Verifique se há vírgulas dentro dos campos (ex: títulos com subtítulos), e utilize aspas duplas para encapsular o conteúdo, se necessário

• Sempre revise um pequeno lote de livros antes de importar grandes quantidades

Compatibilidade

O formato CSV aceito é compatível com exportações do Excel, LibreOffice, Google Sheets, e também com outros sistemas de gerenciamento de bibliotecas que suportam exportação simples.

Exportação de Catálogo e Relatórios

O Hypatia oferece aos administradores duas ferramentas essenciais para a gestão e documentação do acervo: a exportação do catálogo em formato CSV e a geração de relatórios em PDF. Esses recursos são úteis tanto para fins administrativos quanto para auditoria, backup e apresentação institucional.

Exportando o catálogo em CSV

O botão “Exportar Catálogo para CSV” permite que você baixe uma cópia completa do acervo em formato .csv, compatível com Excel, LibreOffice, Google Sheets e outros sistemas bibliográficos.

O que está incluído no arquivo:

Cada linha do arquivo representa um livro, com os campos:

• Título

• Autor

• Editora

• Ano

• ISBN

• Localização

• Idioma

• Quantidade de exemplares

• Link para versão digitalizada (se houver)

• Data de inclusão

Como exportar:

1. Acesse o menu Administração ▾ → Administração de Catálogo

2. Clique em Exportar Catálogo para CSV

3. O download será iniciado automaticamente

Esse recurso é ideal para backup, edição offline, integração com outros sistemas ou visualização rápida dos dados.

Gerando relatórios em PDF

Além do CSV, o Hypatia permite que você gere um relatório em PDF com todos os livros registrados no acervo, formatado para impressão ou envio institucional.

Estrutura do relatório:

• Capa com data e nome da instituição (se configurado)

• Lista formatada de livros, com título, autor, editora, ano e ISBN

• Numeração de páginas automática

Utilizações comuns:

• Apresentação do acervo em eventos ou reuniões

• Relatórios periódicos de manutenção e crescimento do acervo

• Arquivo impresso de referência para bibliotecas físicas

Como gerar:

1. Acesse Administração de Catálogo

2. Clique em Gerar Relatório em PDF

3. Aguarde o processamento e o download automático

📌 Observações

• Ambos os formatos refletem o estado atual do acervo no momento da exportação.

• As exportações incluem apenas livros efetivamente cadastrados; registros com erro ou incompletos são automaticamente ignorados.

• Os arquivos gerados são independentes e não comprometem o funcionamento interno do sistema.

Gestão de Empréstimos

Acessando o painel de empréstimos

• No menu superior, clique em Administração ▾ → Gerenciar Empréstimos

• Você será direcionado à lista de todos os empréstimos registrados n

Solicitando e aprovando empréstimos

Usuários autenticados podem solicitar o empréstimo de livros disponíveis diretamente na página da obra. Assim que uma solicitação é enviada:

• Ela aparece no painel com status pendente

• O administrador pode clicar em “Aprovar” ou “Recusar” a solicitação

Ao aprovar, o sistema:

• Atualiza o status para aprovado

• Registra a data de empréstimo

• Calcula a previsão de devolução (se essa lógica estiver configurada)

Devolvendo obras

Ao receber o livro de volta, o administrador pode:

1. Acessar o painel de empréstimos

2. Localizar o item na lista

3. Clicar em “Registrar Devolução”

O status é alterado para “devolvido”, encerrando o ciclo daquele empréstimo e liberando o título para novas solicitações.

Informações exibidas por empréstimo:

• Título da obra

• Nome do usuário solicitante

• Data da solicitação

• Status atual (pendente, aprovado, devolvido)

• Ações disponíveis (aprovar, recusar, devolve

🔐 Controle de acesso

• Apenas administradores têm acesso ao painel completo de empréstimos

• Usuários comuns podem visualizar seus próprios empréstimos e acompanhar seus status

📌 Boas práticas

• Realize auditorias regulares no painel para manter a lista de empréstimos atualizada

• Utilize o campo de data de devolução para monitorar prazos e atrasos

• Incentive os usuários a consultarem seus empréstimos para acompanhar responsabilidades