Guia de Administração Introdução Hypatia é uma plataforma web desenvolvida para auxiliar no gerenciamento, catalogação e uso avançado de acervos bibliográficos. Pensado para atender pesquisadores, bibliotecários, docentes e leitores organizados, o sistema permite a realização de cadastro e consultas livros, permitindo também controlar empréstimos, marcar obras favoritas e gerar referências bibliográficas nos estilos ABNT e APA com facilidade. 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 O sistema Hypatia pode ser instalado de forma simples tanto em ambientes locais (para testes e desenvolvimento) quanto em servidores de produção com suporte a Gunicorn + Nginx, ideal para implantações públicas ou institucionais. A seguir, descrevemos os dois modos de instalação disponíveis. 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. 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 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 O sistema Hypatia utiliza envio de e-mails para funções essenciais como: Confirmação de cadastro de usuários Notificações de aprovação de registro Alertas sobre empréstimos Recuperação de acesso (futuramente) Para que esses recursos funcionem corretamente, é necessário configurar um servidor SMTP válido, que será usado para o disparo dos e-mails transacionais da plataforma. 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 O sistema Hypatia possui um painel dedicado ao gerenciamento de usuários, acessível exclusivamente por administradores. Através dele, é possível acompanhar os registros, aprovar novos acessos, definir permissões e manter o controle de segurança e uso da plataforma. Acessando o painel de usuários No menu superior, clique em Administração ▾ 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 O módulo de Administração do Acervo do Hypatia permite que os administradores gerenciem o conjunto de obras disponíveis na plataforma de maneira prática e organizada. Através dele, é possível adicionar livros manualmente, editar registros existentes, remover entradas obsoletas e até mesmo importar ou exportar catálogos inteiros em formato CSV. Acessando o painel administrativo No menu superior, clique em Administração ▾ 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 No menu superior, clique em Administração ▾ → Adicionar Livros Deixe o campo ISBN em branco Marque a opção  Este livro não possui ISBN Preencha manualmente os campos obrigatórios, como Título , Autor e demais informações disponíveis 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: Limpa e normaliza o ISBN digitado, convertendo ISBN-10 em ISBN-13, se necessário. Verifica se o livro já está cadastrado no banco de dados local para evitar duplicações. 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 Se nenhuma das fontes retornar dados , o sistema informa que o livro não foi encontrado, e o administrador poderá preencher os campos manualmente. 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 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 Acesse o menu: Administração ▸ Administração de Catálogo Na seção Importar Lista de ISBNs , clique em Selecionar Arquivo CSV . 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 Acesse o menu Administração ▾ → Administração de Catálogo Clique no botão Importar CSV Selecione o arquivo .csv do seu computador 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: Acesse o menu Administração ▾ → Administração de Catálogo Clique em Exportar Catálogo para CSV 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: Acesse Administração de Catálogo Clique em Gerar Relatório em PDF 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 O módulo de Empréstimos do Hypatia oferece aos administradores controle total sobre o fluxo de circulação das obras, permitindo o acompanhamento de solicitações, a aprovação ou recusa de pedidos, e o registro formal de devoluções. Essa funcionalidade torna o sistema ideal não apenas para catalogação, mas também para uso ativo em bibliotecas físicas e centros de documentação. 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: Acessar o painel de empréstimos Localizar o item na lista 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