doctoralia-scrapper 1.2.0

Sistema profissional de monitoramento e resposta a avaliações médicas. Inclui web scraping resiliente, API REST, análise de sentimento, geração inteligente de respostas e integração com n8n/Telegram.

Pipeline Docker-first para scraping de reviews, geração de respostas e relatórios Telegram com API, dashboard, Redis/RQ, Selenium e n8n.

Wiki · Quickstart · API REST · Dashboard · Telegram · n8n · About

Por que este projeto existe

Este repositório organiza uma rotina operacional completa para reviews do Doctoralia. Em vez de tratar scraping como um script solto, ele une coleta, análise, geração de respostas, snapshots persistidos, histórico, observabilidade e distribuição por Telegram em uma mesma stack local.

O que você encontra aqui

Bloco	O que faz
api	Expõe endpoints sync e async, settings, health, metrics e notificações Telegram
worker	Processa scraping, análise, geração e snapshots em background
dashboard	Workspace visual para operação diária, histórico, relatórios e scheduler
redis	Fila RQ, métricas Redis-backed, agendamentos, locks e histórico
selenium	Navegador remoto para scraping resiliente
n8n	Orquestrações externas, callbacks e automações multi-sistema

Tour visual

Workspace operacional Perfis, pendências, saúde da stack, relatórios e histórico de snapshots.	Scheduler Telegram Recorrência, scraping novo, geração, anexos, health e histórico persistido.

Como a stack funciona

Início rápido

Docker

cp .env.example .env
cp config/config.example.json config/config.json

docker compose up -d --build
docker compose ps

URLs locais esperadas:

• API: http://localhost:8000/docs
• Dashboard: http://localhost:5000
• Telegram scheduling: http://localhost:5000/notifications/telegram/schedule
• n8n: http://localhost:5678 com Basic Auth configurada no .env
• Selenium status: http://localhost:4444/status

Desenvolvimento local

make venv
cp .env.example .env
cp config/config.example.json config/config.json

make api
make dashboard

Comandos úteis:

make run-url URL="https://www.doctoralia.com.br/medico/exemplo"
make run-full URL="https://www.doctoralia.com.br/medico/exemplo"
make test
make lint

Endpoints que importam

Método	Endpoint	Uso
POST	/v1/scrape:run	Scraping síncrono
POST	/v1/jobs	Cria job assíncrono
GET	/v1/jobs/{job_id}	Consulta job
GET	/v1/ready	Readiness com Redis, Selenium e NLTK
GET	/v1/metrics	Métricas da API persistidas em Redis
GET/POST/PUT/DELETE	/v1/notifications/telegram/schedules	CRUD do scheduler Telegram
POST	/v1/notifications/telegram/schedules/{schedule_id}/run	Disparo manual
GET	/v1/notifications/telegram/history	Histórico persistido
POST	/v1/notifications/telegram/test	Validação real do bot
POST	/v1/hooks/n8n/scrape	Webhook dedicado do n8n

Estado atual do projeto

Tema	Situação
Stack Docker	api, worker, dashboard, redis, selenium, n8n
Workspace web	Operacional e com scheduler Telegram integrado
Persistência	Snapshots em data/ e histórico/schedules em Redis
Métricas da API	Redis-backed, multi-processo
n8n local	preso em 127.0.0.1:5678, com auth e encryption key obrigatórias
Testes	250 passed
Coverage	74%

Redis em localhost:6379

Se você abrir http://localhost:6379 no navegador e receber ERR_EMPTY_RESPONSE, isso é esperado.

• Redis está rodando.
• O browser fala HTTP.
• Redis não fala HTTP.

Validação correta:

docker compose exec -T redis redis-cli ping

Saída esperada:

PONG

Wiki do repositório

O README agora é só a entrada. A documentação foi reorganizada em formato de wiki dentro de docs/.

Página	Para que serve
docs/Home.md	Hub principal da wiki
docs/about.md	Texto de vitrine, metadata e assets do repositório
docs/quickstart.md	Setup rápido
docs/overview.md	Arquitetura e responsabilidades
docs/dashboard-workspace.md	Operação diária no dashboard
docs/telegram-notifications.md	Scheduler Telegram completo
docs/api.md	Referência da API
docs/n8n.md	Workflows e integração externa
docs/operations.md	Runbook e troubleshooting
docs/development.md	Padrões de desenvolvimento
docs/deployment.md	Guia de deploy
docs/templates.md	Templates e mensagens

Assets visuais adicionados

• docs/assets/logo.svg
• docs/assets/banner.svg
• docs/assets/social-card.svg
• docs/assets/workflow-platform.svg
• docs/assets/workflow-telegram.svg

Convenções técnicas

• Imports internos padronizados em formato absoluto: from src... e from config...
• Dependências gerenciadas por poetry
• Formatação com black e isort
• Testes com pytest

Limitações atuais

• Rate limiting global da API REST ainda não existe como middleware completo.
• O scheduler recorrente depende da API estar de pé.
• Ainda há espaço para subir coverage em src/scraper.py, src/response_generator.py, src/telegram_notifier.py e src/dashboard.py.

Licença

MIT