btgo-playwright/README.md

BTGO Scraper - Automatizare Citire Solduri

Prezentare

Automatizare Playwright pentru extragerea soldurilor și tranzacțiilor din George (btgo.ro).

Arhitectură

BTGO Scraper (btgo_scraper.py)

Entry point: btgo_scraper.py
│
├─ config.py (Config.validate())
│  └─ .env (load credentials)
│
├─ sync_playwright() → Chromium browser
│
├─ BTGOScraper.run()
│  ├─ login()
│  │  ├─ page.goto('go.bancatransilvania.ro')
│  │  ├─ page.expect_popup() → self.login_page
│  │  └─ Fill credentials + submit
│  │
│  ├─ handle_2fa_wait()
│  │  └─ Poll URL + #accountsBtn (120s)
│  │
│  ├─ read_accounts()
│  │  ├─ Click #accountsBtn
│  │  ├─ Iterate fba-account-details-card
│  │  └─ Extract: h4, IBAN, strong.sold
│  │
│  ├─ download_transactions() [optional]
│  │  ├─ For each account:
│  │  │  ├─ Expand card (idx=1 only)
│  │  │  ├─ Click "Tranzacții" (idx=1) / Select from modal (idx>1)
│  │  │  ├─ Click CSV button
│  │  │  └─ page.expect_download()
│  │  └─ Save to data/tranzactii_*.csv
│  │
│  ├─ save_results()
│  │  ├─ Write data/solduri_*.csv
│  │  └─ Write data/solduri_*.json
│  │
│  └─ send_notifications() [optional]
│     └─ notifications.py
│        ├─ EmailNotifier.send()
│        │  └─ SMTP (smtplib)
│        └─ TelegramNotifier.send()
│           └─ requests.post(telegram API)
│
Standalone scripts:
│
├─ send_notifications.py (manual notification send)
├─ get_telegram_chat_id.py (telegram setup helper)
└─ test_telegram.py (telegram connectivity test)

Telegram Trigger Bot (telegram_trigger_bot.py)

Entry point: telegram_trigger_bot.py
│
├─ .env (TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USER_IDS)
│
├─ TelegramTriggerBot.__init__()
│  ├─ Load config from .env
│  ├─ Parse allowed user IDs
│  └─ Initialize Telegram API (api.telegram.org)
│
├─ run()
│  ├─ send_message(startup notification)
│  └─ While True:
│     ├─ get_updates(long_polling timeout=60s)
│     ├─ Parse incoming messages
│     └─ handle_command()
│        │
│        ├─ /scrape command:
│        │  ├─ is_user_allowed(user_id)
│        │  ├─ send_message("🤖 Scraper pornit...")
│        │  ├─ subprocess.run(['python', 'btgo_scraper.py'])
│        │  │  └─ btgo_scraper.py (full execution)
│        │  └─ send_message("✅ Succes" / "❌ Eroare")
│        │
│        ├─ /status command:
│        │  └─ send_message(bot uptime info)
│        │
│        └─ /help command:
│           └─ send_message(available commands)
│
Windows Service:
│
└─ deployment/windows/nssm/
   ├─ BTGOTelegramBot (Windows Service)
   │  ├─ nssm install BTGOTelegramBot
   │  ├─ Auto-restart on failure
   │  └─ Log: logs/telegram_bot_*.log
   │
   Deploy scripts:
   ├─ deploy.ps1 (full deployment)
   ├─ install_service.ps1
   ├─ start_service.ps1
   ├─ restart_service.ps1
   ├─ uninstall_service.ps1
   └─ menu.ps1 (interactive management)

Puncte cheie depanare:

• Scraper login fails: Check selectors în btgo_scraper.py:159-200
• Scraper 2FA timeout: Check URL polling în btgo_scraper.py:202-240
• Scraper account reading fails: Check selectors în btgo_scraper.py:242-310
• Scraper transaction download timeout: Check modal logic în btgo_scraper.py:312-420
• Bot commands not working: Check TELEGRAM_ALLOWED_USER_IDS în .env
• Bot unauthorized: User ID not in allowed list
• Notifications fail: Check notifications.py + config .env

Funcționalități:

• ✅ Citire automată solduri pentru toate conturile
• ✅ Export CSV cu tranzacții pentru fiecare cont
• ✅ Autentificare 2FA automată (auto-detect)
• ✅ Notificări Email și Telegram cu fișierele generate

⚠️ LIMITARE: Docker/headless NU funcționează - WAF-ul site-ului blochează activ containere Docker.

Prerequisites

• Python 3.8+
• Cont BTGO activ cu 2FA
• Windows (Docker nu este suportat)

Instalare pe VM Windows

# Clonare proiect
git clone https://gitea.romfast.ro/romfast/btgo-playwright.git
cd btgo-playwright

# Setup automat (instaleaza Python venv + dependente + Playwright browsers)
deployment\windows\scripts\setup_dev.ps1

# Configurare credentiale in .env
# Editează .env și adaugă:
# BTGO_USERNAME=your_username
# BTGO_PASSWORD=your_password
# HEADLESS=false

# Rulare scraper
deployment\windows\scripts\run_scraper.ps1

Setup și Rulare

Setup Automat (RECOMANDAT)

# PowerShell (recomandat)
deployment\windows\scripts\setup_dev.ps1

# SAU meniu interactiv complet
deployment\windows\scripts\menu.ps1

Rulare Manuală

# Scraper direct
deployment\windows\scripts\run_scraper.ps1

# Telegram bot (manual mode)
deployment\windows\scripts\run_telegram_bot_manual.ps1

# SAU meniu interactiv
deployment\windows\scripts\menu.ps1

Ce se întâmplă:

1. Browser Chrome se deschide vizibil
2. Login automat
3. Așteaptă aprobare 2FA pe telefon (120s timeout)
4. Citește soldurile tuturor conturilor
5. Descarcă CSV-uri cu tranzacții
6. Salvează rezultate în data/

Configurare .env

# Obligatorii
BTGO_USERNAME=your_username
BTGO_PASSWORD=your_password
HEADLESS=false  # OBLIGATORIU false!

# Opționale
DOWNLOAD_TRANSACTIONS=true
TIMEOUT_2FA_SECONDS=120

Structură Output

data/
├── solduri_2025-11-06_14-30-45.csv              # Rezumat solduri
├── solduri_2025-11-06_14-30-45.json             # Metadata + solduri
├── tranzactii_Colector_01_2025-11-06.csv        # Tranzacții per cont
└── dashboard_2025-11-06_14-30-45.png            # Screenshot

logs/
└── scraper_2025-11-06.log                       # Log zilnic

Format CSV Solduri

timestamp,nume_cont,iban,sold,moneda,tip_cont
2025-11-06 14:30:45,Colector 01,RO32BTRLRONCRT0637236701,7223.26,RON,colector

Notificări (Email & Telegram)

Email (SMTP)

# .env
ENABLE_NOTIFICATIONS=true
EMAIL_ENABLED=true
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password  # Pentru Gmail: https://myaccount.google.com/apppasswords
EMAIL_FROM=your-email@gmail.com
EMAIL_TO=recipient@gmail.com

Telegram

1. Crează Bot:

   • Caută @BotFather în Telegram
   • Trimite /newbot
   • Copiază token-ul primit

2. Obține Chat ID:

   python get_telegram_chat_id.py
   

3. Configurare .env:

   ENABLE_NOTIFICATIONS=true
   TELEGRAM_ENABLED=true
   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
   TELEGRAM_CHAT_ID=-1001234567890  # Negativ pentru grupuri
   

Trimitere Manuală Notificări

python send_notifications.py

Telegram Trigger Bot - Declanșare Remote

Setup Rapid (Manual Mode)

1. Configurare .env:

   TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrs
   TELEGRAM_ALLOWED_USER_IDS=your_user_id
   TELEGRAM_CHAT_ID=-1001234567890  # Pentru grup (negativ!)
   

2. Pornire bot:

   deployment\windows\scripts\run_telegram_bot_manual.ps1
   

3. Comenzi disponibile:

   • /scrape - Execută BTGO scraper
   • /status - Status bot
   • /help - Ajutor

Deploy ca Windows Service (RECOMANDAT pentru VM)

# Deploy complet + instalare serviciu
deployment\windows\scripts\deploy.ps1

# SAU folosește meniul interactiv
deployment\windows\scripts\menu.ps1

Avantaje serviciu:

• ✅ Pornire automată cu Windows
• ✅ Auto-restart la crash
• ✅ Rulează în background (fără RDP activ)
• ✅ Logging centralizat

Notă: Fișierele sunt trimise de scraper prin notificări (dacă ENABLE_NOTIFICATIONS=true), NU de bot.

⚠️ Cerință pentru scraper: Desktop Windows activ (RDP conectată) - browser TREBUIE vizibil!

Ghid complet: deployment/windows/README.md și TELEGRAM_BOT_SETUP.md

Troubleshooting

"Access Denied" în Docker

Cauză: WAF-ul BT George blochează Docker/headless browsers. Soluție: Rulează DOAR local în Windows cu HEADLESS=false.

Timeout la 2FA

• Mărește timeout: TIMEOUT_2FA_SECONDS=180 în .env
• Verifică notificări activate pe telefon

Selectors nu funcționează

Site-ul s-a schimbat. Re-generează selectors:

.venv\Scripts\activate
playwright codegen https://btgo.ro --target python

Notificări Email nu funcționează

• Pentru Gmail: folosește App Password, nu parola normală
• Verifică port: 587 (TLS) sau 465 (SSL)
• Testare: python test_telegram.py

Notificări Telegram nu funcționează

• Verifică TELEGRAM_ENABLED=true
• Rulează python test_telegram.py
• Chat ID pentru grupuri trebuie să fie negativ (ex: -1001234567890)
• Asigură-te că botul este în grup

Securitate

⚠️ IMPORTANT:

• NU comite .env în git (deja în .gitignore)
• NU partaja screenshots/logs - conțin date sensibile
• Șterge fișierele vechi periodic:

# Windows
del /q data\*.csv data\*.json data\*.png

# Linux/Mac
rm data/*.{csv,json,png}

Exit Codes

• 0 - Success
• 1 - Eroare generală
• 4 - Eroare configurare (.env invalid)
• 99 - Eroare neașteptată

Licență

MIT License

Disclaimer Legal

Acest tool accesează informații personale bancare. Utilizatorul este singurul responsabil pentru conformarea cu termenii Băncii Transilvania și legislația aplicabilă.