nadogranja

README.md

@@ -1,31 +1,83 @@
 # Mail Checker
 
-**Mail Checker** je funkcionalna Python aplikacija koja radi u sistemskoj traci (System Tray) i omogućuje 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 zadnjih poruka izravno unutar aplikacije, te sigurno pohranjivanje lozinki pomoću sustavnog privjeska ključeva (Keyring).
+**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 (`notify-send`).
+  - 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 sadržaj zadnjih poruka ili ih trajno obrisati (prebaciti u *Trash*).
+- **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 internetske veze.
+- **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)
 
-## 🛠️ Zahtjevi i instalacija
+Kako bi aplikacija radila bez ikakvih pogrešaka i upozorenja u terminalu, potrebno je instalirati sve sistemske biblioteke i Python pakete.
 
-Aplikacija je optimizirana za Linux sustave (testirano na Debian/Ubuntu distribucijama).
+### 1.">Instalacija sistemskih paketa (APT)
 
-### 1. Instalacija sistemskih ovisnosti
-
-Za punu funkcionalnost (notifikacije, zvuk i glas), instalirajte sljedeće pakete putem upravitelja paketima:
+Otvorite terminal i pokrenite sljedeću naredbu kako biste instalirali **sve** potrebne pakete za grafiku, zvuk, obavijesti i privjesak ključeva:
 
 ```bash
 sudo apt update
-sudo apt install espeak-ng mpv libayatana-appindicator3-1 python3-tk
+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