Praćenje Računa preko Telegram Bota

Automatsko praćenje komunalnih računa pomoću Telegram bota sa GPT-4 Vision AI analizom i Power BI integracijom.

Funkcionalnosti

• Automatska OCR analiza računa - Fotografišite račun i bot automatski izvlači podatke
• Praćenje više adresa - Odvojeno praćenje za različite lokacije
• Kategorije računa - Struja, Informatika, Vodovod, Internet, itd.
• Praćenje potrošnje struje - Automatsko beleženje kWh potrošnje
• Detaljne statistike - Pregled troškova po periodima, adresama i kategorijama
• Poređenje perioda - Analiza trendova kroz vreme
• SQLite baza podataka - Lokalno skladištenje podataka
• REST API - Power BI integracija za napredne analize
• Srpski jezik - Kompletna lokalizacija interfejsa

Zahtevi

• Python 3.12+
• Telegram Bot Token (@BotFather)
• OpenAI API Key (GPT-4 Vision)
• Linux server (opciono, za deployment)

Brza Instalacija

1. Klonirajte repozitorijum

git clone https://github.com/yourusername/telegram-bill-tracker.git
cd telegram-bill-tracker

2. Kreirajte virtuelno okruženje

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# ili
venv\Scripts\activate  # Windows

3. Instalirajte zavisnosti

pip install -r requirements.txt

4. Konfiguracija

Kreirajte .env fajl:

cp .env.example .env

Popunite .env sa vašim kredencijalima:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
OPENAI_API_KEY=your_openai_api_key_here
ALLOWED_USER_IDS=123456789,987654321
API_KEY=generate_random_key_here

5. Pokrenite bota

python bot.py

Korišćenje

Osnovne komande

• /start - Pokreni bota
• /help - Prikaži pomoć
• /stats - Pregled troškova
• /stats [adresa] - Troškovi za određenu adresu
• /list - Lista računa sa ID brojevima
• /delete [ID] - Obriši račun
• /month - Troškovi ovog meseca
• /compare - Poredi periode obračuna
• /category [adresa] [kategorija] - Filtriraj po kategoriji
• /addresses - Sve adrese
• /export - Izvezi podatke u CSV

Upload računa

1. Fotografišite račun
2. Pošaljite fotografiju botu
3. Izaberite adresu iz liste ili unesite novu
4. Izaberite kategoriju ili unesite novu
5. Bot automatski obrađuje i čuva račun

Kategorije

• Struja - Računi za električnu energiju (sa kWh)
• Informatika - Stanarine, održavanje
• Vodovod - Voda i odvođenje otpadnih voda
• Internet - Internet usluge
• Fiksni - Fiksni telefon
• Drugi fiksni - Dodatni fiksni troškovi
• Ostalo - Ostali računi

REST API

API omogućava integraciju sa Power BI i drugim alatima.

Pokretanje API servera

python api.py

API je dostupan na http://localhost:5002

Ključni endpointi

GET /api/health                    # Health check
GET /api/bills                     # Svi računi
GET /api/bills?category=Struja     # Filtrirani računi
GET /api/line-items                # Sve stavke
GET /api/summary                   # Statistike
GET /api/addresses                 # Sve adrese
GET /api/categories                # Sve kategorije

Detaljnu dokumentaciju potražite u API_DOCS.md.

Power BI Integracija

1. Power BI Desktop → Get Data → Web
2. Unesite URL:

   http://your-server:5002/api/bills?api_key=YOUR_API_KEY
   

3. Koristite Power BI Copilot instrukcije za kreiranje dashboard-a

Deployment na Linux Server

Systemd service za bot

sudo cp billtracker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable billtracker
sudo systemctl start billtracker

Systemd service za API

sudo cp billtracker-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable billtracker-api
sudo systemctl start billtracker-api

Firewall konfiguracija

sudo ufw allow 5002/tcp

Struktura baze podataka

bills tabela

Kolona	Tip	Opis
id	INTEGER	Primarni ključ
date	DATE	Datum izdavanja računa
billing_period	TEXT	Period obračuna (YYYY-MM)
total	REAL	Ukupan iznos
address	TEXT	Adresa
category	TEXT	Kategorija
electricity_kwh	REAL	Potrošnja struje u kWh
created_at	TIMESTAMP	Vreme kreiranja

line_items tabela

Kolona	Tip	Opis
id	INTEGER	Primarni ključ
bill_id	INTEGER	Foreign key na bills
name	TEXT	Naziv stavke
amount	REAL	Iznos

Sigurnost

• API autentifikacija putem API ključa
• Whitelist korisnika za Telegram bota
• Enkriptovani kredencijali u .env fajlu
• SQLite baza sa lokalnim pristupom

Best practices

1. Nikada ne commit-ujte .env fajl
2. Koristite jake API ključeve: openssl rand -hex 32
3. Ograničite pristup API-ju samo na potrebne IP adrese
4. Redovno backup-ujte bills.db

Cene

• Telegram Bot - Besplatno
• Hetzner Cloud Server - ~€3.79/mesec (opciono)
• OpenAI API - $0.02 po računu ($0.40/mesec za 20 računa)

Razvoj

Lokalni development

# Kloniraj repo
git clone https://github.com/yourusername/telegram-bill-tracker.git
cd telegram-bill-tracker

# Setup
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Run bot u development modu
python bot.py

Testiranje

# Test API endpointi
curl http://localhost:5002/api/health

# Test bot (pošaljite poruku u Telegram)

Doprinos

Doprinosi su dobrodošli! Molimo:

1. Fork-ujte repozitorijum
2. Kreirajte feature branch (git checkout -b feature/nova-funkcionalnost)
3. Commit-ujte izmene (git commit -m 'Dodaj novu funkcionalnost')
4. Push-ujte branch (git push origin feature/nova-funkcionalnost)
5. Otvorite Pull Request

Licenca

MIT License - pogledajte LICENSE fajl za detalje.

Prijava bagova

Prijavite bagove putem GitHub Issues.

Molimo uključite:

• Opis problema
• Korake za reprodukciju
• Očekivano ponašanje
• Snimke ekrana (ako je relevantno)
• Informacije o okruženju (OS, Python verzija)

Kontakt

Za pitanja i podršku, otvorite issue ili kontaktirajte autora.

Zahvalnice

• python-telegram-bot
• OpenAI GPT-4 Vision
• Flask
• Power BI

---