📖 Manual do Sistema PubMed

1. Visão geral ↑ topo

O módulo PubMed é um agregador pessoal de literatura científica que consulta a API pública do NCBI PubMed. Permite:

• Pesquisar artigos usando termos configuráveis (afiliações, autores, MeSH, etc.)
• Receber alertas automáticos quando surgem novos artigos correspondentes a esses termos
• Marcar artigos como favoritos, visitados, atribuir classificação por estrelas e adicionar notas
• Consultar estatísticas e os artigos melhor avaliados

A arquitectura é simples: um script Python corre via cron e alimenta a base de dados; as páginas PHP consomem essa BD e chamam a API PubMed apenas quando necessário (ex: abstracts ainda não em cache).

2. Páginas do módulo ↑ topo

3. Como usar a pesquisa ↑ topo

Chips de termos

No topo da página de pesquisa aparecem chips para cada termo activo. Por omissão todos estão seleccionados (fundo accent). Clica num chip para o desactivar — os artigos desse termo deixam de aparecer nos resultados.

Filtros de data

Os campos De e Até limitam os resultados por ano de publicação. O botão 📅 Último mês activa um filtro para artigos publicados nos últimos 30 dias (limpa os filtros de ano).

Ordenação

• Data ▼ — ordem cronológica inversa (mais recentes primeiro)
• Relevância — ordenação do PubMed por relevância para os termos da query

Campo de texto livre

Adiciona termos adicionais em linguagem natural ou com qualificadores PubMed ([Author], [MeSH Terms], etc.). É combinado com os chips seleccionados via AND. Premindo Enter pesquisa imediatamente.

Acções por artigo

• ❤️ Favorito — guarda nas listas pessoais (ver Guardados)
• 👁 Marcar visitado — o card fica com opacidade reduzida; activa-se automaticamente ao abrir o abstract
• ★★★★★ — classificação pessoal de 1 a 5 estrelas
• 📝 Notas — campo de texto livre, guardado ao sair do campo (blur)
• PubMed ↗ / DOI ↗ / PMC ↗ — links externos para o artigo original

Clicar no título do artigo abre o abstract (descarregado da API em tempo real, com cache automática) e marca-o como visitado.

Paginação

25 artigos por página. A navegação rola automaticamente para o topo da lista ao mudar de página.

4. Termos de pesquisa e sintaxe PubMed ↑ topo

Os termos são geridos em /pubmed/termos.php (requer login). Cada termo tem:

• Nome — etiqueta curta exibida nos chips e nos alertas (ex: FMUP)
• Query PubMed — expressão enviada directamente à API NCBI
• Descrição — texto explicativo opcional
• Activo/Inactivo — toggle; termos inactivos não aparecem nos chips nem são pesquisados pelo monitor

Termos activos de momento

Sintaxe das queries PubMed

O PubMed suporta qualificadores de campo entre parêntesis rectos. Exemplos úteis:

Operadores lógicos: AND, OR, NOT. Múltiplos termos num mesmo chip devem ser ligados com OR:

"CINTESIS"[Affiliation] OR "CINTESIS"[Author Affiliation]

"Universidade do Porto"[Affiliation] AND "cardiology"[MeSH Terms]

5. Alertas de novos artigos ↑ topo

Sempre que o monitor detecta um artigo que ainda não foi alertado, insere um registo em pubmed_alertas com visto=0. Esse registo aparece em /pubmed/alertas.php com um ponto verde.

Marcar como visto

• Clicar no título de um alerta marca-o automaticamente como visto (via JavaScript)
• O botão ✓ Marcar todos como vistos actualiza todos de uma vez

Badge na navbar

O número de alertas não vistos aparece como badge laranja no menu de navegação, ao lado de "Alertas". Actualiza a cada carregamento de página.

Limite de apresentação

A página mostra os 200 alertas mais recentes (o histórico completo fica na BD). Os artigos sem metadados na cache aparecem apenas com o PMID até que o monitor os processe.

6. Serviço de monitorização (monitor.py) ↑ topo

Localização e configuração

/home/pi/pubmed/monitor.py   # script principal
/home/pi/pubmed/monitor.log  # log de execuções

A configuração está no dicionário CONFIG no início do ficheiro:

Agendamento (cron)

Corre 4 vezes por dia, de 6 em 6 horas, com output para o log:

0 0,6,12,18 * * *  /usr/bin/python3 /home/pi/pubmed/monitor.py >> /home/pi/pubmed/monitor.log 2>&1

O que o monitor faz em cada execução

1. Lê os termos activos da BD (pubmed_termos WHERE ativo=1)
2. Para cada termo: chama esearch.fcgi com a query + filtro de data (últimos 7 dias) → obtém lista de PMIDs
3. Descarta os PMIDs já presentes em pubmed_alertas
4. Para os novos: chama esummary.fcgi em lotes de 50 para obter metadados
5. Insere os artigos em pubmed_artigos e cria registo em pubmed_alertas com visto=0
6. Associa o artigo ao termo em pubmed_artigo_termos
7. Faz commit à BD e (se configurado) envia email

Correr manualmente

python3 /home/pi/pubmed/monitor.py

Ver o log em tempo real

tail -f /home/pi/pubmed/monitor.log

Exemplo de output normal:

2026-06-07 06:00:01 [INFO] === Monitor PubMed iniciado ===
2026-06-07 06:00:01 [INFO] A pesquisar: FMUP
2026-06-07 06:00:02 [INFO]   → 16 PMIDs encontrados
2026-06-07 06:00:02 [INFO]   → 2 novos (não alertados ainda)
2026-06-07 06:00:03 [INFO] A pesquisar: CINTESIS
2026-06-07 06:00:04 [INFO]   → 10 PMIDs encontrados
2026-06-07 06:00:04 [INFO]   → 0 novos (não alertados ainda)
2026-06-07 06:00:07 [INFO] Total de novos artigos: 4
2026-06-07 06:00:07 [INFO] === Monitor concluído ===

Obter uma API Key NCBI (opcional)

Sem chave o monitor respeita o limite de 3 req/s (pause de 350 ms entre pedidos). Com chave sobe para 10 req/s. Para activar:

1. Regista conta em ncbi.nlm.nih.gov/account
2. Vai a Settings → API Key Management e gera uma chave
3. Em /home/pi/pubmed/monitor.py, edita: "api_key": "TUA_CHAVE_AQUI"

7. Notificações por email ↑ topo

O monitor pode enviar um email sempre que encontra artigos novos. Por omissão está desactivado. Para activar, edita /home/pi/pubmed/monitor.py:

"email": {
    "enabled":   True,                    # activar
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "user":      "tua_conta@gmail.com",   # conta de envio
    "password":  "password_app_gmail",    # password de app (não a da conta)
    "para":      "jagsilva+pubmed@gmail.com",
},

O email lista até 20 artigos com título truncado e link directo para o PubMed.

8. Estrutura da base de dados ↑ topo

Todas as tabelas estão na base de dados analytics e são criadas automaticamente na primeira execução de db.php.

pubmed_termos

pubmed_artigos

Cache local dos metadados vindos da API NCBI esummary.fcgi.

pubmed_interacoes

Dados pessoais por artigo — um registo por PMID.

pubmed_alertas

pubmed_artigo_termos

Tabela de ligação many-to-many entre artigos e termos (para os badges coloridos nos cards).

Consultas úteis

# Alertas por ver
mysql -u jagsilva -praspberry analytics \
  -e "SELECT COUNT(*) FROM pubmed_alertas WHERE visto=0;"

# Artigos em cache
mysql -u jagsilva -praspberry analytics \
  -e "SELECT COUNT(*) FROM pubmed_artigos;"

# Últimos alertas detectados
mysql -u jagsilva -praspberry analytics \
  -e "SELECT pmid, termo_id, created_at FROM pubmed_alertas ORDER BY created_at DESC LIMIT 10;"

9. API REST (endpoints) ↑ topo

Todos os endpoints estão em /pubmed/api/ e devolvem JSON.

10. Manutenção e diagnóstico ↑ topo

Verificar se o cron está configurado

crontab -l | grep pubmed

Deve aparecer: 0 0,6,12,18 * * * /usr/bin/python3 /home/pi/pubmed/monitor.py ...

Verificar a última execução

tail -20 /home/pi/pubmed/monitor.log

Correr o monitor manualmente e ver output

python3 /home/pi/pubmed/monitor.py

O monitor não encontra artigos novos

• Normal se a janela de 7 dias não tiver artigos novos para esses termos
• Verifica se os termos estão activos em /pubmed/termos.php
• Testa a query directamente no PubMed para confirmar que devolve resultados
• Aumenta dias_atras temporariamente para verificar se a query funciona

Erro de ligação à API NCBI

O log mostrará [ERROR] Erro NCBI esearch.fcgi: .... Causas comuns:

• Sem ligação à internet no Raspberry Pi
• Rate limit excedido (aguarda alguns minutos e tenta de novo)
• API Key inválida (experimenta sem chave, deixando api_key: "")

Limpar alertas antigos

# Apagar alertas com mais de 6 meses já marcados como vistos
mysql -u jagsilva -praspberry analytics \
  -e "DELETE FROM pubmed_alertas WHERE visto=1 AND created_at < DATE_SUB(NOW(), INTERVAL 6 MONTH);"

Ficheiros relevantes