PyPrestaScan 🔍

Scanner SEO professionale per PrestaShop con sistema di fix automatici

PyPrestaScan è uno strumento open-source avanzato per l'analisi SEO completa di siti PrestaShop. Scansiona il tuo e-commerce, identifica problemi SEO critici e genera suggerimenti automatici per risolverli.

📦 Installazione rapida: pip install 'pyprestascan[gui]'

👨‍💻 Autore

Andrea Piani Full-Stack Developer & SEO Specialist

🔗 Link: linktr.ee/andreapianidev

Progetto open-source in continuo miglioramento! Contributi, feedback e segnalazioni sono sempre benvenuti. 🚀

📋 Roadmap: ROADMAP.md - Piano sviluppo v1.2.0 → v2.0.0 🤝 Contributing: CONTRIBUTING.md - Guida per contributor

🎯 Caratteristiche Principali

📊 Analisi SEO Completa

• Crawling intelligente con supporto sitemap.xml e robots.txt
• Rilevamento automatico di prodotti, categorie, CMS e filtri faceted
• Analisi approfondita di meta tag, title, headings, canonical, hreflang
• Controllo immagini con rilevamento ALT mancanti, vuoti o generici
• Rilevamento duplicati tramite content hash
• Scoring SEO per ogni pagina con severity (CRITICAL, WARNING, INFO)

🔧 Sistema di Fix Suggeriti + AI-Powered (v1.1.0 🆕)

• 🤖 Generazione AI intelligente con DeepSeek, OpenAI GPT o Anthropic Claude
• Meta description contestuali generate dall'AI invece di template generici
• Batch processing: 20 prodotti in 1 chiamata = -30% token
• Costi ultra-bassi: ~$0.02 per 500 prodotti (DeepSeek)
• Fallback automatico: se AI fallisce, usa template standard
• Suggerimenti intelligenti per:
  • 🎯 Meta description mancanti o non ottimizzate (AI-powered!)
  • 📝 Title troppo corti o troppo lunghi
  • 🖼️ ALT text mancanti per le immagini
  • 🔗 Canonical URL mancanti
  • 📋 H1 multipli o mancanti
  • 🌍 Hreflang mancanti
• Confidence scoring (0-100%) per ogni fix suggerito
• Export SQL per fix automatizzabili
• Export CSV con dettagli completi

💡 AI Fix: Esempio Reale

Template Standard:

"Scarpe Nike Air Zoom - Acquista online su myshop.it"

AI DeepSeek (v1.1.0):

"Scarpe Nike Air Zoom: ammortizzazione reattiva per running. Scopri la collezione 2024 con tecnologia React Foam!"

Differenza: Contestuale, benefici evidenziati, CTA naturale. Confidence: 0.95 vs 0.70. Costo: $0.00004 per prodotto.

🎨 Interfaccia Grafica Moderna

• GUI intuitiva con Qt/PySide6
• 4 Tab principali:
  1. ⚙️ Configurazione: setup URL, limiti, concorrenza
  2. 📊 Progress & Log: monitoraggio real-time con log dettagliati
  3. 📈 Risultati: statistiche, tabella issues filtrabili
  4. 🔧 Fix Suggeriti: visualizza e gestisci i fix automatici
• Log in tempo reale durante la scansione
• Contatori live (pagine crawlate, issues trovati, immagini senza ALT)
• Filtri avanzati per issues e fix
• Export multipli (CSV, JSON, HTML, SQL)

📈 Report Dettagliati

• Report HTML interattivo con grafici e tabelle
• Export CSV/JSON per analisi dati
• Export SQL per applicazione fix diretta al database
• Visualizzazione issues per severity e tipologia
• Dashboard statistiche complete

⚡ Performance & Scalabilità

• Crawling asincrono con concorrenza configurabile (default: 20 worker)
• Rate limiting automatico per non sovraccaricare il server
• Database SQLite per gestione efficiente dei dati
• Resume support per riprendere scansioni interrotte
• Gestione memoria ottimizzata per siti con migliaia di pagine

🚀 Installazione

Requisiti

• Python 3.8+ (3.12+ raccomandato)
• pip

📦 Installazione da PyPI (Consigliata)

# Installazione base (CLI)
pip install pyprestascan

# Con interfaccia grafica (NOTA: su zsh/macOS usa le virgolette)
pip install 'pyprestascan[gui]'

# Avvia la GUI
pyprestascan-gui

# Oppure usa la CLI
pyprestascan scan https://tuosito.com/it/ --max-urls 1000

🔧 Installazione da sorgenti (Development)

# Clona il repository
git clone https://github.com/andreapianidev/pyprestascan.git
cd pyprestascan

# Installa in modalità development (NOTA: su zsh/macOS usa le virgolette)
pip install -e '.[gui]'

# Avvia l'interfaccia grafica
python -m pyprestascan.gui.main_window

# Oppure usa la CLI
python -m pyprestascan scan https://tuosito.com/it/ --max-urls 1000

📖 Utilizzo

Interfaccia Grafica (Consigliata)

1. Avvia la GUI:

   # Se installato da PyPI
   pyprestascan-gui
   
   # Oppure se installato da sorgenti
   python -m pyprestascan.gui.main_window
   

2. Configura la scansione:

   • Inserisci l'URL del tuo sito PrestaShop
   • Imposta il numero massimo di pagine da analizzare
   • Configura concorrenza e altre opzioni avanzate

3. Avvia la scansione:

   • Clicca su "▶️ Avvia Scansione"
   • Monitora il progresso in tempo reale nel tab "Progress & Log"

4. Analizza i risultati:

   • Vai al tab "📊 Risultati" per vedere gli issues rilevati
   • Filtra per severity (Critical, Warning, Info)
   • Esporta in CSV per analisi dettagliate

5. Genera e applica fix:

   • Vai al tab "🔧 Fix Suggeriti"
   • Clicca su "Genera Fix Suggeriti"
   • Visualizza i fix con confidence score
   • Esporta SQL per applicarli direttamente al database PrestaShop

🤖 Utilizzo AI Fix (v1.1.0+)

PyPrestaScan può usare AI generativa per creare meta description di qualità superiore:

1. Registrati su un provider AI (raccomandato: DeepSeek):

   • DeepSeek - $5 credito gratuito!
   • OpenAI - GPT-4o-mini
   • Anthropic - Claude Haiku

2. Configura in PyPrestaScan:

   • Vai in tab Configurazione → sezione "AI Fix Avanzati (Opzionale)"
   • Spunta "✨ Abilita generazione AI per Fix Suggeriti"
   • Seleziona provider (es: DeepSeek)
   • Inserisci la tua API key

3. Genera fix intelligenti:

   • Esegui scansione normalmente
   • Tab Fix Suggeriti → clicca "Genera Fix Suggeriti"
   • L'AI creerà meta description contestuali invece di template generici
   • Costo stimato: ~$0.02 per 500 prodotti (DeepSeek)

💰 Confronto Costi AI

Risparmio vs lavoro manuale: 8 ore ($240) → 30 secondi ($0.02) = 99.99% di risparmio!

📖 Documentazione completa: Leggi AI_INTEGRATION.md per guide dettagliate, troubleshooting e best practices.

Command Line Interface (CLI)

# Scansione base (se installato da PyPI)
pyprestascan scan https://tuosito.com/it/

# Oppure se installato da sorgenti
python -m pyprestascan scan https://tuosito.com/it/

# Scansione con opzioni avanzate
pyprestascan scan https://tuosito.com/it/ \
  --max-urls 5000 \
  --concurrency 30 \
  --timeout 20 \
  --project mio-progetto \
  --export-dir ./reports

# Riprendi scansione interrotta
pyprestascan scan https://tuosito.com/it/ --resume

# Debug mode
python -m pyprestascan scan https://tuosito.com/it/ --debug

# Quiet mode (solo errori)
python -m pyprestascan scan https://tuosito.com/it/ --quiet

📋 Regole SEO Implementate

PyPrestaScan controlla automaticamente oltre 20 regole SEO PrestaShop-specific:

🔴 Critical Issues

• TITLE_MISSING: Title tag mancante
• TITLE_TOO_SHORT: Title < 10 caratteri
• TITLE_TOO_LONG: Title > 60 caratteri
• META_DESCRIPTION_MISSING: Meta description mancante
• H1_MISSING: Tag H1 mancante
• H1_MULTIPLE: Più di un H1 nella pagina
• CANONICAL_MISSING: Canonical URL mancante
• PRODUCT_NO_JSONLD: Prodotto senza JSON-LD

🟡 Warning Issues

• META_DESCRIPTION_TOO_SHORT: Description < 50 caratteri
• META_DESCRIPTION_TOO_LONG: Description > 160 caratteri
• IMAGES_MISSING_ALT: Immagini senza attributo ALT
• IMAGES_EMPTY_ALT: Immagini con ALT vuoto
• CART_INDEXABLE: Carrello indicizzabile (bad practice)
• FACETED_NO_CANONICAL: Filtri faceted senza canonical

🔵 Info Issues

• IMAGES_GENERIC_ALT: ALT text generico ("image", "photo", etc.)
• NO_HREFLANG: Hreflang mancante (siti multilingua)
• SLOW_TTFB: Time To First Byte > 1000ms

🔧 Sistema di Fix Automatici

Tipi di Fix Supportati

1. Meta Description Fixer

   • Genera description ottimizzate 120-160 caratteri
   • Basate su title e tipologia pagina
   • Confidence: 50-90% (dipende dalla qualità del title)

2. Title Fixer

   • Ottimizza lunghezza title (10-60 caratteri)
   • Tronca title lunghi preservando il significato
   • Espande title corti aggiungendo brand
   • Confidence: 60-90%

3. ALT Text Fixer

   • Suggerisce ALT text basato su contesto pagina
   • Richiede revisione manuale (confidence: 50%)
   • Template-based per prodotti/categorie

4. Canonical Fixer

   • Genera canonical URL auto-referenziali
   • Rimuove parametri query non necessari
   • Confidence: 90% (alta affidabilità)

Come Usare i Fix

1. Genera fix dopo la scansione:

   • Tab "Fix Suggeriti" → "Genera Fix Suggeriti"
   • Attendi alcuni secondi per la generazione

2. Visualizza i fix:

   • Tabella con tutti i fix ordinati per severity e confidence
   • Filtri per status, tipo, automatizzabili

3. Dettagli fix:

   • Clicca sull'icona 👁️ per vedere:
     • Valore attuale vs suggerito
     • Spiegazione del problema
     • Query SQL per applicare il fix

4. Esporta ed applica:

   • Export CSV: per revisione manuale
   • Export SQL: script pronto per l'esecuzione
   • ⚠️ Fai sempre un backup prima di applicare le query SQL!

📁 Struttura File Export

Dopo ogni scansione, PyPrestaScan genera:

report/
├── crawl.db              # Database SQLite con tutti i dati
├── report.html           # Report interattivo con grafici
├── pages.csv             # Dettagli di tutte le pagine
├── issues.csv            # Tutti gli issues rilevati
├── images_missing_alt.csv # Immagini con problemi ALT
├── duplicates.csv        # Contenuti duplicati
├── fixes.csv             # Fix suggeriti (dopo generazione)
└── fixes.sql             # Script SQL per fix automatici

🛠️ Configurazione Avanzata

Parametri CLI Principali

Filtri URL Avanzati

# Include solo categorie e prodotti
python run_cli.py scan https://shop.com \
  --include "/category/.+" \
  --include "/.*-p\\d+\\.html"

# Escludi parametri di ordinamento
python run_cli.py scan https://shop.com \
  --exclude "\\?.*orderby=" \
  --exclude "\\?.*selected_filters="

🤝 Contribuire

PyPrestaScan è un progetto open-source e in continuo miglioramento!

Contributi, segnalazioni bug e feature request sono sempre benvenuti:

1. Fai fork del repository
2. Crea un branch per la tua feature (git checkout -b feature/AmazingFeature)
3. Commit delle modifiche (git commit -m 'Add some AmazingFeature')
4. Push al branch (git push origin feature/AmazingFeature)
5. Apri una Pull Request

Roadmap Futura

• Integrazione API PrestaShop per applicazione fix automatica
• Supporto multi-lingua migliorato
• Analisi performance (Core Web Vitals)
• Monitoraggio scheduled con notifiche
• Plugin per PrestaShop back-office
• AI-powered content suggestions
• Report PDF professionali
• Export Excel nativo

🚨 Risoluzione Problemi

Problemi Comuni

❌ "Bloccato da robots.txt"

# Verifica robots.txt manualmente
curl https://tuo-sito.com/robots.txt

⚡ Crawling lento

# Aumenta concorrenza (attenzione al server)
python run_cli.py scan https://sito.com --concurrency 50

# Riduci delay se robots.txt lo permette
python run_cli.py scan https://sito.com --delay 0

💾 Errori di memoria

# Riduci concorrenza per grandi siti
python run_cli.py scan https://sito.com --concurrency 10 --max-urls 20000

Log e Debug

# Debug completo
python run_cli.py scan https://sito.com --debug

# Log minimal
python run_cli.py scan https://sito.com --quiet

🔒 Sicurezza e Privacy

Responsabilità

• Rispetta robots.txt e ToS dei siti
• Non fare overload sui server di destinazione
• Autentica appropriatamente per siti privati
• Proteggi credenziali in ambienti condivisi

Rate Limiting Responsabile

# Per siti piccoli/medi
python run_cli.py scan https://shop.com --delay 100 --concurrency 20

# Per siti grandi/condivisi
python run_cli.py scan https://shop.com --delay 500 --concurrency 10

🤖 Integrazione e API

Script Python

import asyncio
from pyprestascan.cli import CrawlConfig, CliContext
from pyprestascan.core.crawler import PyPrestaScanner

async def custom_scan():
    config = CrawlConfig(
        base_url="https://myshop.com",
        max_urls=5000,
        concurrency=20
    )

    cli_context = CliContext(debug=False, quiet=False, no_color=False)
    scanner = PyPrestaScanner(config, cli_context)
    return await scanner.run()

# Esegui
asyncio.run(custom_scan())

Export Dati

import pandas as pd

# Carica dati da CSV
pages_df = pd.read_csv('report/pages.csv')
issues_df = pd.read_csv('report/issues.csv')

# Analisi personalizzate
low_score_pages = pages_df[pages_df['score'] < 50]
critical_issues = issues_df[issues_df['severity'] == 'CRITICAL']

📄 Licenza

Questo progetto è distribuito con licenza MIT - vedi il file LICENSE per i dettagli.

🙏 Ringraziamenti

• PrestaShop Community per la fantastica piattaforma e-commerce
• PySide6 per il framework GUI
• httpx per le richieste HTTP async
• BeautifulSoup4 per il parsing HTML
• Tutti i contributori che aiutano a migliorare il progetto

📞 Supporto

Per domande, bug o feature request:

• 🐛 Issues GitHub: github.com/andreapianidev/PyPrestaScan/issues
• 💬 Discussioni: github.com/andreapianidev/PyPrestaScan/discussions
• 🔗 Contatto diretto: linktr.ee/andreapianidev

⭐ Star History

Se PyPrestaScan ti è stato utile, considera di lasciare una ⭐ su GitHub!