mail_checker/README.md

Mail Checker

Mail Checker je napredna i potpuno funkcionalna Python aplikacija koja radi unutar sistemske trake (System Tray) i služi za praćenje nepročitanih poruka s više IMAP računa istovremeno. Aplikacija podržava zvučne obavijesti, glasovna upozorenja na hrvatskom jeziku (TTS), pregled i čitanje zadnjih poruka kroz tabove, te sigurno pohranjivanje lozinki.

Napomena o kompatibilnosti: Ova aplikacija je razvijena isključivo za Linux sustave, a službeno je testirana i optimizirana na Debian 13 (Trixie) operativnom sustavu.

✨ Funkcionalnosti

• Praćenje više računa: Sinkronizirana provjera više e-mail računa s različitim IMAP poslužiteljima.
• Fleksibilni intervali: Svaki račun može imati vlastiti interval provjere (minimalno 10 sekundi).
• Napredne obavijesti:
  • Desktop notifikacije preko sistemskog daemon-a (notify-send).
  • Prilagođene zvučne datoteke (.wav, .mp3) za svaki račun zasebno.
  • Glasovni alert (TTS): Izgovaranje broja nepročitanih poruka na hrvatskom jeziku uz ispravnu gramatičku deklinaciju (npr. 1 poruku, 2 poruke, 5 poruka) s izborom muškog ili ženskog glasa.
• Pregled poruka: Sučelje s tabovima unutar kojeg možete pročitati tekstualni sadržaj zadnjih poruka ili ih trajno obrisati (prebaciti u Trash).
• Visoka sigurnost: Integracija sa sistemskim privjeskom ključeva (keyring) – lozinke se ne zapisuju u plain-text obliku unutar konfiguracijske datoteke ako je privjesak dostupan.
• Otpornost na mrežne greške: Implementiran exponential backoff mehanizam za ponovne pokušaje u slučaju gubitka mrežne veze.

🛠️ Potpuni zahtjevi i instalacija (Debian 13)

Kako bi aplikacija radila bez ikakvih pogrešaka i upozorenja u terminalu, potrebno je instalirati sve sistemske biblioteke i Python pakete.

1.">Instalacija sistemskih paketa (APT)

Otvorite terminal i pokrenite sljedeću naredbu kako biste instalirali sve potrebne pakete za grafiku, zvuk, obavijesti i privjesak ključeva:

sudo apt update
sudo apt install python3-tk python3-pil python3-pystray python3-keyring \
                 espeak-ng mpv libayatana-appindicator3-1 libayatana-appindicator-glib1 \
                 libnotify-bin gir1.2-gtop-2.0 dbus-x11

**Pojašnjenje paketa:**
- `python3-tk`: Omogućuje rad Tkinter grafičkog sučelja u Pythonu.
- `python3-pil`: Pillow biblioteka za generiranje i manipulaciju ikona u sistemskoj traci.
- `python3-pystray`: Omogućuje kreiranje i upravljanje ikonom u sistemskoj traci.
- `python3-keyring`: Omogućuje Pythonu komunikaciju sa sustavnim privjeskom ključeva za sigurno spremanje lozinki.
- `espeak-ng`: TTS pokretač koji generira glasovne obavijesti na hrvatskom jeziku.
- `mpv`: Moćan media player koji aplikacija koristi u pozadini za reprodukciju `.mp3` i `.wav` dateka bez blokiranja sučelja.
- `libayatana-appindicator3-1` & `libayatana-appindicator-glib1`: Sustavne biblioteke ključne za ispravan prikaz ikone u traci (AppIndicator) na modernim Linux radnim okruženjima.
- `libnotify-bin`: Omogućuje slanje skočnih desktop obavijesti putem naredbe `notify-send`.
- `dbus-x11`: Osigurava stabilnu komunikaciju aplikacije sa sistemskim servisima (notifikacije, keyring) unutar X11/Wayland sesije.

### 4. Pokretanje aplikacije
```markdown
## 🚀 Pokretanje aplikacije

Aplikaciju pokrećete iz njezinog direktorija standardnom naredbom:

```bash
python3 mail_checker.py

### 5. Korisničko sučelje (Postavke i Pregled)
```markdown
## ⚙️ Korisničko sučelje (Postavke i Pregled)

### Upravljanje računima
Prozor za postavke podijeljen je na dva dijela:
1. **Lijeva strana**: Popis registriranih računa s horizontalnim klizačem za dugačke adrese te gumbima ▲/▼ za promjenu redoslijeda provjere.
2. **Desna strana**: Formular za unos detalja računa (Nadimak, IMAP Server, Email, Lozinka, Interval, Zvučna datoteka, TTS postavke i opcije pregleda).

### Pregled poruka
Klikom na **Pregled poruka** unutar izbornika sistemske trake otvara se prozor koji povlači najnovije poruke za sve račune koji imaju uključenu opciju prikaza. Dvostrukim klikom na poruku otvara se prozor za čitanje tekstualnog sadržaja s opcijom izravnog brisanja poruke sa servera.

## 📁 Struktura datoteka

Aplikacija unutar svog direktorija koristi i stvara sljedeće datoteke:
- `mail_checker.py` - Glavni izvorni kôd aplikacije.
- `config.json` - Konfiguracijska datoteka u kojoj se čuvaju postavke računa (lozinke su izostavljene ako se koristi `keyring`).
- `mail_checker.log` - Detaljan dnevnik rada i pogrešaka (Log file).

## 🔒 Sigurnost lozinki (Keyring Helper)

Aplikacija automatski prepoznaje podržava li vaše radno okruženje na Debianu privjesak ključeva (npr. *GNOME Keyring* ili *KDE Wallet*).
- **Ako je privjesak dostupan**: Polje `"MAIL_PASSWORD"` unutar `config.json` ostat će prazno (`""`), a lozinka se sigurno pohranjuje u sustav pod servisom `MailChecker`.
- **Ako privjesak nije dostupan** (npr. minimalne ili headless instalacije): Aplikacija će zapisati upozorenje u log te će automatski spremiti lozinku lokalno unutar datoteke `config.json` kako bi osigurala kontinuitet rada.

## 🐛 Rješavanje problema i Dnevnik (Logging)

Sve akcije, promjene stanja, uspješni dohvati, kao i IMAP ili mrežne pogreške konstantno se zapisuju u datoteku `mail_checker.log`. U slučaju bilo kakvih problema s povezivanjem na e-mail poslužitelj, otvorite log datoteku kako biste vidjeli točan uzrok:

```bash
tail -f mail_checker.log