💧 BillDrop

Trascina, rilascia, fatto. Rinomina e archivia automaticamente le tue bollette PDF.

BillDrop è uno strumento Python leggero che legge le tue bollette in PDF, riconosce il fornitore, classifica il tipo di servizio (gas, luce, internet) e le rinomina e sposta automaticamente nelle cartelle giuste — mostrando un'anteprima completa prima di toccare qualsiasi file.

---

✨ Funzionalità

• 📄 Parsing automatico dei PDF — rileva il fornitore ed estrae il periodo di fatturazione dal testo del documento
• 🗂️ Archiviazione intelligente — sposta ogni bolletta nella cartella corretta in base al tipo di servizio (gas, luce, internet)
• 🔢 Numerazione progressiva — i file vengono numerati in sequenza all'interno di ogni cartella (1) ..., 2) ...)
• 🔍 Rilevamento duplicati — scansione MD5 per evitare sovrascritture; i duplicati vengono segnalati e salvati come copie
• 👁️ Anteprima live — mostra esattamente cosa accadrà prima di spostare qualsiasi file
• 🧩 Supporto drag and drop — trascina file o cartelle direttamente sull'eseguibile
• ⚙️ Wizard di configurazione guidato — al primo avvio (o con --setup) guida passo passo nella configurazione
• 📋 Log rotativi — storico completo delle esecuzioni salvato in logs/app.log, ruotato automaticamente per dimensione

---

🚀 Per iniziare

Requisiti

• Python 3.11+
• pdfplumber

pip install -r requirements.txt

Primo avvio

python main.py

Se non viene trovato nessun config.json, il wizard di configurazione parte automaticamente e genera il file per te.

Per riavviare il wizard in qualsiasi momento:

python main.py --setup

💡 Vuoi azzerare la configurazione? Elimina semplicemente il file config.json e riavvia il programma: il wizard ripartirà dall'inizio come al primo avvio.

Drag and drop

Trascina uno o più file PDF (o intere cartelle) direttamente su bollette.exe. BillDrop li processerà usando le cartelle definite in config.json.

---

⚙️ Configurazione

BillDrop viene configurato tramite config.json:

{
  "input_folder": "input",
  "output_folder": "output",
  "unknown_behaviour": "skip",
  "rename_patterns": {
    "DEFAULT": "{supplier}_{document_type}_{period}",
    "TIM": "{period}",
    "SINERGAS": "{supplier}_{document_type}_{period}"
  },
  "destination_folders": {
    "LUCE": "output/luce",
    "GAS": "output/gas",
    "INTERNET": "output/internet",
    "UNKNOWN": "output/unknown"
  }
}

Chiave	Descrizione
input_folder	Cartella da cui leggere i PDF
output_folder	Cartella di output base
unknown_behaviour	skip per lasciare intoccati i file non riconosciuti, move per spostarli nella cartella unknown
rename_patterns	Template del nome file per fornitore. Placeholder disponibili: {supplier}, {document_type}, {period}
destination_folders	Cartella di destinazione per tipo di servizio

---

🏗️ Struttura del progetto

BillDrop/
├── core/
│   ├── config.py            # Caricamento e validazione configurazione
│   ├── duplicate_checker.py # Rilevamento duplicati via MD5
│   ├── logger.py            # Logger su file e console con rotazione
│   ├── models.py            # Dataclass DocumentInfo
│   ├── mover.py             # Logica di spostamento file
│   ├── pdf_reader.py        # Estrazione testo da PDF
│   ├── parser_manager.py    # Orchestrazione parser
│   ├── renamer.py           # Costruzione nome file
│   ├── service_classifier.py# Classificatore GAS / LUCE / INTERNET
│   ├── setup_wizard.py      # Wizard di configurazione interattivo
│   └── warnings.py          # Tipi di warning personalizzati
├── parsers/
│   ├── base.py              # Parser astratto base
│   ├── sinergas.py          # Parser Sinergas
│   └── tim.py               # Parser TIM
├── logs/                    # Cartella log (generata automaticamente)
├── input/                   # Cartella di input PDF
├── output/                  # Output ordinato
├── main.py
├── icon.ico                 # Icona dell'eseguibile
├── config.json
└── requirements.txt

---

🔌 Aggiungere un nuovo fornitore

1. Crea parsers/tuofornitore.py estendendo BaseParser
2. Implementa detect(text) e extract(text)
3. Registralo in parser_manager.py

Nessun'altra modifica necessaria.

---

📦 Compilare come eseguibile (Windows)

pip install pyinstaller
pyinstaller --onefile --name bollette main.py

L'eseguibile si troverà in dist/bollette.exe. Puoi spostarlo dove vuoi, ma deve trovarsi nella stessa cartella di config.json.

Per aggiungere un'icona personalizzata:

pyinstaller --onefile --name bollette --icon=icon.ico main.py

Il file icona deve essere in formato .ico.

Se ottieni errori di import con pdfplumber:

pyinstaller --onefile --name bollette --collect-all pdfplumber main.py

---

📝 Licenza

MIT